@esp-vision/device-core 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## 0.4.1 (unreleased)
+## [Unreleased]
+
+### Changed
+
+- Move the host management CLI to the standalone `@esp-vision/device-cli` package and keep passive Node inventory helpers available from `@esp-vision/device-core/node`.
+
+### Fixed
+
+- Detach started Python runs from connection-lifetime cancellation after VM entry, so normal disconnect releases ownership without sending a remote stop; retain caller AbortSignal cancellation.
+
+- Wait for a private VM-entry sentinel before resolving detached Python startup, with bounded startup waits and session-isolated output.
+
+- Add validated `connect({ probeRepl: false })` for non-interrupting native RPC access and use it for metadata inventory probes; retain the existing active connection default.
+
+- Make aggregate deadlines optional by default for completed Python runs and file reads while retaining bounded REPL exchanges and per-chunk file-read limits.
+- Keep wait-mode small-source execution on the REPL until its completion sentinel arrives, without imposing a fixed program-completion timeout or requiring device storage.
+
+## 0.4.2
+
+### Fixed
+
+- Route browser ROM reset calls through the active flash stub after upload, preserving its two-byte status decoder during P4 watchdog register writes; report reset failure diagnostics without invalidating successful firmware verification.
+
+## 0.4.1
 
 ### Fixed
 

package/README.md

@@ -19,10 +19,10 @@
 | Visibility | Public; installation needs no npm login |
 | Source location | `host/device-core` in the ESP-VISION firmware repository |
 
-This source prepares **0.4.0 (not published by this change)** with browser ROM flashing, immutable release-manifest readers and application updates from a single complete BIN. npm 0.3.0 does not contain these APIs. The `/node` byte transports and bundled checks require 0.1.1; complete installation and `/node` `openNodeRom` are introduced in 0.3.0. Check the registry before using the 0.4.0 install examples; until publication, use a tarball packed from an exact reviewed source commit. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
+The latest public npm release is **0.4.2**. This source prepares **0.5.0 (not yet published)**: Core becomes an SDK-only package, the management CLI moves to `@esp-vision/device-cli`, and Python execution/file reads have no aggregate deadline unless configured. Pin the exact package version and verify it exists in the public registry before installing. Until publication, use a tarball packed from an exact reviewed source commit. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
 
 ```sh
-npm install --save-exact @esp-vision/device-core@0.4.0 --registry=https://registry.npmjs.org/
+npm install --save-exact @esp-vision/device-core@0.5.0 --registry=https://registry.npmjs.org/
 ```
 
 EV-MUX v4 firmware is required. A v3 hello is rejected with `VERSION_MISMATCH`; applications should ask the user to update firmware. Core has no runtime dependency on the IDE, Agent, DOM or Node serial libraries. The host supplies the physical byte transport and discovery adapter; Core owns protocol parsing, session negotiation, REPL coordination and device operations.
@@ -38,10 +38,10 @@ Documentation source lives in this repository under `docs/en/device-core/` and `
 
 ## Management CLI
 
-The npm package installs `esp-vision-device`. `inspect` combines passive wired/LAN enumeration and targeted queries. By default it lists USB serial candidates; `--all-ports` also includes native UART/Bluetooth ports. Explicit `--port` bypasses discovery filtering; `configure`, `control`, and `firmware check/update` cover management. See the [CLI guide](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/cli.html) ([中文](https://docs.espressif.com/projects/esp-vision/zh_CN/latest/esp32p4/device-core/cli.html)).
+Starting with 0.5.0, Device Core is a library and does not install a management command. Existing 0.4.x installations retain their command until explicitly upgraded or removed. Install the independent `@esp-vision/device-cli` package when you need the device toolkit. It uses the public Core APIs and is installed explicitly; Device Core does not fetch or wrap the CLI. See the [CLI guide](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/cli.html) ([中文](https://docs.espressif.com/projects/esp-vision/zh_CN/latest/esp32p4/device-core/cli.html)).
 
 ```sh
-npm install -g @esp-vision/device-core@0.4.0
+npm install -g @esp-vision/device-cli
 esp-vision-device inspect
 esp-vision-device inspect --all-ports
 esp-vision-device inspect --interface usj,usb --probe --json
@@ -110,7 +110,9 @@ try {
 }
 ```
 
-### Immutable release snapshots and a single firmware BIN (0.4.0, unpublished)
+`connect()` sends Ctrl-C and a short REPL liveness probe by default for compatibility. Pass `probeRepl: false` when a detached application may be running: Core still acquires the EV-MUX session and reads identity/capabilities, but leaves the REPL untouched. In this mode a reported `vmReady: false` stays false; Python operations that require a ready VM fail with a readiness error.
+
+### Immutable release snapshots and a single firmware BIN
 
 The `/firmware` entry exports `loadOfficialFirmware({ board?, version?, fetch?, signal? })` and `loadReleaseManifest({ url, sha256, version?, sourceCommit?, boards?, fetch?, signal? })`. The official reader prioritizes `[publication]` in `config.toml`, selects exactly one version reference and verifies its raw manifest SHA-256 before returning `{ schemaVersion: 1, version, sourceCommit, pipelineId, layout, releases, website, mcp?, publication }`. History references include exact board sets; unsupported board/version combinations and malformed explicit publication data reject without falling back to guessed URLs or old metadata. Configs without `[publication]` keep the legacy feed; an explicit version limits old metadata requests too.
 
@@ -128,11 +130,11 @@ const release = snapshot.releases.find(entry => entry.board === selectedBoard);
 
 In `layout: 'single-bin'`, `image.source = { url, bytes, sha256, offset }` describes the complete BIN; `image.url` equals its URL, while `image.bytes/sha256` still describe only the application. The source URL/length/hash must match `install`, and its offset must equal the application's flash offset. Core downloads the full container once (no Range request), validates its whole hash and embedded bootloader/partition/application hashes, then extracts and writes only the application in default update mode. Existing partition checks and full application readback remain mandatory; `mode: 'install'` writes the qualified complete BIN. With `image.source`, supplied `data` must also be the complete BIN; old application-only metadata keeps its existing raw-app `data` semantics. Manifests are bounded at 4 MiB, firmware downloads at 256 MiB and their approved exact size. Official manifest/artifact sources are confined to the ESP-VISION CDN root; model URLs use their full source commit and MCP has a version/commit/hash descriptor. No npm, firmware tag or CDN publication is performed by preparing this source version.
 
-To validate before npm publication, check out an exact reviewed commit, run `npm install --ignore-scripts --no-audit --no-fund --package-lock=false` and `npm run release:check` in `host/device-core`, then `npm pack --ignore-scripts --pack-destination <project-local-output>`. Install that locally produced tarball or use a source archive pinned to that exact commit. Do not claim that an unpublished 0.4.0 is available in the registry.
+To validate before npm publication, check out an exact reviewed commit, run `npm install --ignore-scripts --no-audit --no-fund --package-lock=false` and `npm run release:check` in `host/device-core`, then `npm pack --ignore-scripts --pack-destination <project-local-output>`. Install that locally produced tarball or use a source archive pinned to that exact commit.
 
-### Browser ROM flashing (unreleased)
+### Browser ROM flashing
 
-`@esp-vision/device-core/browser` exports `openBrowserRom({ port, logger?, signal? })`. Build from this branch until a new SDK release is published; installing 0.3.0 does not enable this API. The constructor is passive, and `initialize()` lazily loads the pinned `tasmota-webserial-esptool` browser backend. Use a browser bundler such as webpack, Vite or esbuild; direct native ESM loading of the upstream backend is not supported. No Python installation or consumer-side tasmota patch is needed. The root and `/node` entry points do not load browser modules.
+`@esp-vision/device-core/browser` exports `openBrowserRom({ port, logger?, signal? })`. The constructor is passive, and `initialize()` lazily loads the pinned `tasmota-webserial-esptool` browser backend. Use a browser bundler such as webpack, Vite or esbuild; direct native ESM loading of the upstream backend is not supported. No Python installation or consumer-side tasmota patch is needed. The root and `/node` entry points do not load browser modules.
 
 ```js
 import { createDevice } from '@esp-vision/device-core';
@@ -153,6 +155,8 @@ Core owns downloads, chip/revision/security and partition/capacity checks, write
 
 ### Official Node adapters
 
+The public Node entry also exports `inventory`, `listSerial`, `filterSerialPorts`, `serialEntry`, `transportFor` and `defaultPython`. Enumeration is passive unless `inventory({ probe: true })` is explicitly requested; cancellation is supported. Bundlers obtain the exact published Python adapters from `nodeAdapterAssets()`, which returns `{ serial: URL, rom: URL }` without opening a port or running Python.
+
 The Node-only `@esp-vision/device-core/node` subpath exports `tcpTransport({ host, port })` and `serialTransport({ serial, python })`. Constructors are passive; Core opens/closes the link during `connect()`/`disconnect()`. Serial needs pyserial in the selected Python interpreter, and uses role `usj`, `usb` or `uart` for the actual interface. The root/browser entry points do not load Node networking/process modules.
 
 ```js
@@ -238,7 +242,11 @@ await device.python.execute({ path: '/main.py', completion: 'start' });
 unsubscribe();
 ```
 
-`source` and `path` are mutually exclusive. `completion: 'wait'` (the default) returns `{ ok, path, output, outputTruncated }` after the program finishes. `'start'` returns `{ ok, path, done }` after starting it; await `done` for the execution result. Source started this way uses an internal temporary script that Core removes after execution. Terminal input, scripts and filesystem helpers share one MicroPython interpreter. The application should not send terminal input while an automated operation owns the REPL. Conflicting automated operations reject with `DEVICE_BUSY`; Core does not silently queue them or isolate user Python in a second interpreter. Terminal input remains available to an explicitly started interactive script.
+`source` and `path` are mutually exclusive. `completion: 'wait'` (the default) returns `{ ok, path, output, outputTruncated }` after the program finishes. `'start'` returns `{ ok, path, done }` after Core receives a private VM-entry marker from the generated runner; it does not wait for the program to finish, so a short script may already be done when the handle is returned. Core waits at most five seconds for this start acknowledgement. If it times out or is cancelled, the program may have entered and Core does not claim that it stopped. Await `done` for the execution result. Once the start handle is returned, `device.disconnect()` releases the session without requesting a stop; `done` rejects locally as the session closes, and the device program may continue. A caller-provided `signal` remains bound until `done` settles and requests a stop if aborted while the session is available. Source started this way uses an internal temporary script that Core removes after execution; disconnect can prevent this cleanup. Terminal input, scripts and filesystem helpers share one MicroPython interpreter. The application should not send terminal input while an automated operation owns the REPL. Conflicting automated operations reject with `DEVICE_BUSY`; Core does not silently queue them or isolate user Python in a second interpreter. Terminal input remains available to an explicitly started interactive script.
+
+Small `source` requests with `completion: 'wait'` run through the existing REPL without creating a device file, so they work when storage is unmounted and do not require `script.run` or `file.write.binary`. Core holds the source in a temporary REPL variable, executes it in the normal global namespace so user variables remain available, and deletes only that temporary variable after completion. Source larger than the REPL input limit uses a temporary device script and requires `script.run`, `file.write.binary`, and writable storage.
+
+For `completion: 'wait'`, omitting `timeout` disables the aggregate operation deadline; a positive `timeout` limits the full operation, including its REPL queue and startup exchanges. Core still bounds each REPL exchange and RPC, so an omitted total deadline does not create an unbounded protocol wait. If a timeout or cancellation occurs while code is running, its effects may be uncertain; Core does not claim that the program stopped or roll back device changes.
 
 ### Files and images
 
@@ -259,7 +267,7 @@ const image = await device.capture({ source: 'camera', format: 'jpeg', timeout:
 // image: { data: Uint8Array, mimeType: 'image/jpeg', metadata }
 ```
 
-Paths are absolute device paths. `files.list({ path: '/', recursive: false })` returns entries `{ name, path, type, size }`. `files.read({ path })` returns a `Uint8Array`; use `encoding: 'utf-8'` to return text, and `maxBytes` to bound a read. Writes default to `overwrite: true`; set it to `false` to require a new destination. Uploading and executing are separate operations; create an empty file with `files.write({ path, data: new Uint8Array() })` rather than a second touch API. Remove an empty directory with `files.remove({ path: '/models', type: 'directory' })`; there is no implicit recursive deletion. `files.mkdir({ path, recursive: true })` creates missing parents.
+Paths are absolute device paths. `files.list({ path: '/', recursive: false })` returns entries `{ name, path, type, size }`. `files.read({ path })` returns a `Uint8Array`; use `encoding: 'utf-8'` to return text, and `maxBytes` to bound a read. Omitting `timeout` disables the aggregate read deadline; a positive `timeout` limits the full read. Each chunk request remains bounded by `chunkTimeout`, which defaults to 30 seconds. Writes default to `overwrite: true`; set it to `false` to require a new destination. Uploading and executing are separate operations; create an empty file with `files.write({ path, data: new Uint8Array() })` rather than a second touch API. Remove an empty directory with `files.remove({ path: '/models', type: 'directory' })`; there is no implicit recursive deletion. `files.mkdir({ path, recursive: true })` creates missing parents.
 
 **Binary uploads (SDK 0.3.0):** text, model and image uploads share reliable raw binary `file.write` frames with 16 KiB blocks, continuous native VFS writes and SHA-256 commit. Matching firmware must advertise `file.write.binary`; missing support rejects with a firmware-upgrade message, without a slow upload fallback. File progress is not a durable commit. FAT replacement preserves an old-file backup until ordinary publication succeeds, with rollback on ordinary rename failure; it is not a power-loss-atomic journal. The filesystem must be mounted and allow writing, with room for the temporary upload and any existing destination file. File reads and directory operations currently use the REPL.
 
@@ -294,6 +302,8 @@ const devices = await device.discover({ timeout: 3000 });
 
 Results contain `deviceId`, `hostname` (without `.local`), `board`, `firmwareVersion`, `evMuxVersion`, `compatible`, `addresses`, `port`, and adapter-specific `expiresAt`/`connectionUrl`. Supply the selected result as `expectedDevice` when connecting: Core checks the stable ID and hostname before acquisition, protecting against stale DHCP addresses. This is identity matching, not authentication. Refresh expired bridge handles. Multicast filtering, VLANs and client isolation may require a manual address. Browsers have no native DNS-SD enumeration API; local-network permission does not remove the bridge requirement.
 
+Node-only adapters and passive serial inventory are exported from `@esp-vision/device-core/node`: `defaultPython`, `listSerial`, `filterSerialPorts`, `serialEntry`, `transportFor`, and `inventory`. `listSerial({ python, signal, timeout })` runs the bundled Python enumerator with a process timeout and cancellation signal; it lists ports without opening them. `inventory()` lists without probing by default. Pass `probe: true` to acquire each selected EV-MUX session and query metadata; this does not send Ctrl-C or run a REPL probe, and reported `vmReady` state is preserved. Creating a transport with `transportFor()` is passive and does not open the port.
+
 The root/browser entry points do not import Node networking modules. The optional Node discovery subpath dynamically loads `multicast-dns`. No Agent package is required.
 
 ## Migration from the session API
@@ -323,7 +333,7 @@ IDE and Agent adapters that construct sessions or call `session.repl` must migra
 
 ROM flashing remains a separate lifecycle under `@esp-vision/device-core/firmware`. Hosts inject the ROM loader, approved image manifest and reset policy. The adapter validates image integrity, chip/revision, security and partitions, verifies complete readback, and clears the P4 download latch before reset. It does not distribute firmware, open a browser picker or provide a flashing UI. EV-MUX `control({ action: 'bootloader' })` only requests entry into the downloader; it does not flash an image.
 
-Agent workflows, MCP tool mappings, model providers, CLI bundles and plugin packaging belong to the independent Agent project and are not included here.
+Agent workflows, MCP tool mappings, model providers and plugin packaging belong to their own integration packages and are not included here.
 
 ## Validation and release
 
@@ -358,7 +368,7 @@ npm --prefix node_modules/@esp-vision/device-core run test:hardware -- --help
 npm --prefix node_modules/@esp-vision/device-core run test:hardware -- --tcp 192.168.1.100:3232
 ```
 
-Inside the source or installed package directory, use `npm test` and `npm run test:hardware -- ...`. Unit tests require no device. The runner explicitly enumerates tests and fails when the suite is absent or empty, rather than passing zero cases. The management CLI uses `--port`; the dedicated hardware runner uses `--serial`, as shown in its help.
+Inside the source or installed package directory, use `npm test` and `npm run test:hardware -- ...`. Unit tests require no device. The runner explicitly enumerates tests and fails when the suite is absent or empty, rather than passing zero cases. The dedicated hardware runner uses `--serial`, as shown in its help.
 
 Run the source or installed SDK against one idle device using Node.js 22. These checks use the public `createDevice()` API and release the session and transport afterwards. The default check reads identity/capabilities/runtime and executes a short `print()` without creating a device file. Connecting negotiates the REPL, so use a device whose running Python application may safely be interrupted. The check does not configure Wi-Fi, reset the board or erase storage.
 
@@ -379,7 +389,7 @@ These functional checks intentionally exercise sensor settings, image processing
 
 `--screen-output PATH` explicitly requests an LCD screenshot: it adds the `display` check when needed, draws red/green/blue/white bars with `ESP-VISION CI` text, validates backlight changes, captures that same display with `capture({ source: 'screen' })`, verifies JPEG completeness and panel dimensions, and writes the JPEG on the host before releasing the display. Missing LCD or screen capture support makes this explicit request fail instead of skip. Camera capture stays a separate source. Output images and logs should be placed under your project-local artifact directory when running this suite.
 
-TCP needs only Node.js. Serial additionally needs a Python interpreter with the optional [pyserial](https://pyserial.readthedocs.io/) dependency installed in your environment (`python3 -m pip install pyserial`, BSD-3-Clause; not vendored or included in the npm package). Select another interpreter with `--python /path/to/python`. The Apache-2.0-licensed serial adapter in `src/node_serial.py` is shared by the CLI and hardware runner; it enumerates ports without opening them, forwards bytes and configures RTS/DTR before opening; serial control-line behavior still depends on the board and OS driver. The same hardware runner, unit tests and Python fixture ship in the source tree and npm tarball; no firmware/build outputs or device credentials are included.
+TCP needs only Node.js. Serial additionally needs a Python interpreter with the optional [pyserial](https://pyserial.readthedocs.io/) dependency installed in your environment (`python3 -m pip install pyserial`, BSD-3-Clause; not vendored or included in the npm package). Select another interpreter with the `python` option when listing ports or configuring a serial adapter. The Apache-2.0-licensed serial adapter in `src/node_serial.py` is shared by the public Node transport and hardware runner; it enumerates ports without opening them, forwards bytes and configures RTS/DTR before opening; serial control-line behavior still depends on the board and OS driver. The same hardware runner, unit tests and Python fixture ship in the source tree and npm tarball; no firmware/build outputs or device credentials are included.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {
@@ -68,15 +68,11 @@
       "optional": true
     }
   },
-  "bin": {
-    "esp-vision-device": "./src/cli.js"
-  },
   "optionalDependencies": {
     "multicast-dns": "^7.2.5"
   },
   "dependencies": {
     "smol-toml": "^1.7.0",
-    "string-width": "^7.2.0",
     "tasmota-webserial-esptool": "9.4.2"
   },
   "devDependencies": {

package/schemas/device-actions-v1.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "ESP Vision Device Actions",
-  "deviceCoreVersion": "0.4.1",
+  "deviceCoreVersion": "0.5.0",
   "schemaVersion": 1,
   "actions": [
     {

package/src/browser_rom_compat.js

@@ -15,6 +15,13 @@ export function browserRomCompatibility(loader) {
       }
     }
   }
+  // runStub returns a separate loader. Its command replies use two status bytes;
+  // the ROM loader still expects four and cannot issue reset register writes.
+  let activeStub
+  const hardReset = loader.hardReset
+  loader.hardReset = function (...args) {
+    return activeStub ? activeStub.hardReset(...args) : hardReset.apply(this, args)
+  }
   const runStub = loader.runStub
   loader.runStub = async function (skipFlashDetection = false) {
     const memFinish = this.memFinish, packet = this.readPacket
@@ -34,6 +41,7 @@ export function browserRomCompatibility(loader) {
       const stub = await runStub.call(this, skipFlashDetection)
       if (!stub.IS_STUB) throw new Error('This device has no supported browser flash stub')
       browserStubCompatibility(stub)
+      activeStub = stub
       return stub
     } finally { this.memFinish = memFinish; this.readPacket = packet }
   }

package/src/device.js

@@ -106,14 +106,24 @@ class Device {
     source?.addEventListener('abort', abortSource, { once: true })
     if (lifecycle.aborted) abortLifecycle()
     if (source?.aborted) abortSource()
-    const cleanup = () => {
+    const cleanupLifecycle = () => {
       lifecycle.removeEventListener('abort', abortLifecycle)
+    }
+    const cleanup = () => {
+      cleanupLifecycle()
       source?.removeEventListener('abort', abortSource)
     }
     try {
       const result = await api[domain][method]({ ...request, signal: controller.signal })
-      // A started Python run retains cancellation until its completion.
-      if (result?.done instanceof Promise) { result.done.then(cleanup, cleanup); return result }
+      if (result?.done instanceof Promise) {
+        // Once Python reports that a run started, disconnect releases the
+        // session but does not reinterpret that acknowledgement as a request
+        // to interrupt the device program. The caller's own signal remains
+        // attached until completion.
+        if (domain === 'python' && method === 'execute') cleanupLifecycle()
+        result.done.then(cleanup, cleanup)
+        return result
+      }
       cleanup()
       return result
     } catch (error) { cleanup(); throw error }
@@ -125,10 +135,11 @@ class Device {
   }
 
   async connect(options = {}) {
-    object(options, ['transport', 'role', 'expectedDevice', 'timeout', 'signal'], 'connect')
-    const { role = 'unknown', expectedDevice = null, timeout = 30000, signal } = options
+    object(options, ['transport', 'role', 'expectedDevice', 'timeout', 'signal', 'probeRepl'], 'connect')
+    const { role = 'unknown', expectedDevice = null, timeout = 30000, signal, probeRepl = true } = options
     if (!['unknown', 'usj', 'usb', 'uart', 'tcp'].includes(role)) throw new TypeError('role must be usj, usb, uart or tcp')
     if (!Number.isFinite(timeout) || timeout <= 0) throw new RangeError('timeout must be positive')
+    if (typeof probeRepl !== 'boolean') throw new TypeError('probeRepl must be a boolean')
     if (signal !== undefined && (!signal || typeof signal.addEventListener !== 'function' || typeof signal.aborted !== 'boolean')) throw new TypeError('signal must be an AbortSignal')
     if (signal?.aborted) throw cancellation(signal)
     if (this.#updating || this.#connecting || this.#disconnecting || this.#session) throw failure('DEVICE_BUSY', 'Disconnect before opening another connection')
@@ -173,7 +184,7 @@ class Device {
       this.#unsubscribe = transport.subscribe({ data: bytes => { if (this.#session === session) session.feedBytes(bytes) }, error: lost, close: () => lost() })
       if (typeof this.#unsubscribe !== 'function') throw new TypeError('Transport subscribe must synchronously return an unsubscribe function')
       if (transport.connect) await abortable(transport.connect({ signal: lifecycle.signal }), lifecycle.signal)
-      await abortable(session.negotiate({ role, expectedDevice, signal: lifecycle.signal }), lifecycle.signal)
+      await abortable(session.negotiate({ role, expectedDevice, probeRepl, signal: lifecycle.signal }), lifecycle.signal)
       if (lifecycle.signal.aborted || this.#session !== session) throw cancellation(lifecycle.signal)
       this.#api = {
         python: createPythonApi({ session, state: this.#state }),

package/src/device_files.js

@@ -27,13 +27,14 @@ export function createFilesApi({ session, state = {} }) {
       }))
     },
     async read(request) {
-      request = snapshotRequest(request, ['path', 'encoding', 'timeout', 'maxBytes', 'signal'], 'files.read')
-      const { path, encoding = 'binary', timeout = 30000, maxBytes = null, signal = null } = request
+      request = snapshotRequest(request, ['path', 'encoding', 'timeout', 'chunkTimeout', 'maxBytes', 'signal'], 'files.read')
+      const { path, encoding = 'binary', timeout = null, chunkTimeout = 30000, maxBytes = null, signal = null } = request
       if (!['binary', 'utf-8'].includes(encoding)) throw new TypeError('File encoding must be binary or utf-8')
-      if (!Number.isFinite(timeout) || timeout <= 0) throw new RangeError('File read timeout must be positive')
+      if (timeout !== null && (!Number.isFinite(timeout) || timeout <= 0)) throw new RangeError('File read timeout must be positive or null')
+      if (!Number.isFinite(chunkTimeout) || chunkTimeout <= 0) throw new RangeError('File read chunk timeout must be positive')
       if (maxBytes !== null && (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > 16 * 1024 * 1024)) throw new RangeError('maxBytes must be between zero and 16 MiB')
       return operate('read', request, async () => {
-        const bytes = await session.repl.readFile(path, { timeout, maxBytes, signal })
+        const bytes = await session.repl.readFile(path, { timeout, chunkTimeout, maxBytes, signal })
         return encoding === 'binary' ? bytes : new TextDecoder().decode(bytes)
       })
     },

package/src/device_python.js

@@ -53,7 +53,8 @@ function validateRequest(request) {
   if (path) validateDevicePath(request.path)
   const completion = request.completion ?? 'wait'
   if (!['wait', 'start'].includes(completion)) throw new TypeError('Python completion must be wait or start')
-  if (request.timeout !== undefined && (!Number.isFinite(request.timeout) || request.timeout <= 0)) throw new RangeError('Python timeout must be positive')
+  if (request.timeout !== undefined && request.timeout !== null
+      && (!Number.isFinite(request.timeout) || request.timeout <= 0)) throw new RangeError('Python timeout must be positive or null')
   if (request.maxOutputChars !== undefined && (!Number.isSafeInteger(request.maxOutputChars) || request.maxOutputChars < 0)) throw new RangeError('maxOutputChars must be a nonnegative integer')
   if (completion === 'start' && request.timeout !== undefined) throw new TypeError('timeout only applies to completion wait')
   return { source, completion }
@@ -79,7 +80,7 @@ export function createPythonApi({ session, state = {} }) {
     async execute(request) {
       request = snapshotRequest(request, ['source', 'path', 'completion', 'timeout', 'signal', 'maxOutputChars'], 'Python execution')
       const { source, completion } = validateRequest(request)
-      const { signal = null, timeout = 10000, maxOutputChars } = request
+      const { signal = null, timeout = null, maxOutputChars } = request
       checkAbort(signal)
       if (state.operation || state.run || session.runCapture || session.runStarting) throw deviceBusy()
       const token = { kind: 'python.execute', interactive: false }
@@ -93,7 +94,7 @@ export function createPythonApi({ session, state = {} }) {
         if (released) return
         released = true
         try {
-          if (temporary) {
+          if (temporary && session.state === 'ready') {
             if (failed && session.stopForRepl) {
               const ready = await session.stopForRepl({ timeout: 3000 })
               if (!ready) throw Object.assign(new Error('Cannot clean up Python source until REPL is ready'), { code: 'REPL_UNAVAILABLE' })

package/src/device_session.js

@@ -11,6 +11,8 @@
 export const EV_MUX_PAYLOAD_LIMIT = 1800
 export const EV_MUX_SCRIPT_CHUNK_BYTES = 900
 export const EV_MUX_VERSION = 4
+const INLINE_PYTHON_REPL_TIMEOUT_MS = 5000
+const SCRIPT_START_ACK_TIMEOUT_MS = 5000
 // MicroPython has a 128-byte VFS path buffer; script.write also appends .tmp.
 export const EV_MUX_PATH_MAX_BYTES = 123
 export const EV_MUX_DEFAULT_LIMITS = Object.freeze({
@@ -188,6 +190,24 @@ function awaitWithSignal(promise, signal) {
   })
 }
 
+function createOperationDeadline(signal, timeout, timeoutError = Object.assign(new Error('Python execution timed out'), { code: 'TIMEOUT' })) {
+  if (timeout === null) return { signal, dispose() {} }
+  const controller = new AbortController()
+  const abortFromCaller = () => controller.abort(abortError(signal))
+  signal?.addEventListener('abort', abortFromCaller, { once: true })
+  if (signal?.aborted) abortFromCaller()
+  const timer = controller.signal.aborted
+    ? null
+    : setTimeout(() => controller.abort(timeoutError), timeout)
+  return {
+    signal: controller.signal,
+    dispose() {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', abortFromCaller)
+    },
+  }
+}
+
 function withTimeout(operation, timeout, message, signal = null) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
@@ -321,7 +341,7 @@ export class DeviceSession {
     this.runStarting = false
 
     this.repl = new EvRepl({
-      writeEvmux: (channel, type, method, payload) => this.writeFrame(channel, type, method, payload),
+      writeEvmux: (channel, type, method, payload, options) => this.writeFrame(channel, type, method, payload, options),
     })
     this.repl.onScriptEnd = () => this._handleScriptEnd()
 
@@ -521,7 +541,7 @@ export class DeviceSession {
       if (this.runCapture) {
         clearTimeout(this.runCapture.timer)
         this.runCapture = null
-        this.repl.cancelScriptEndSentinel()
+        this.repl.cancelScriptEndSentinel(error)
       }
       this.parser.resetReplTextDecoders?.()
       this.repl.resetEpoch(error)
@@ -1201,44 +1221,59 @@ export class DeviceSession {
     return tracked
   }
 
-  async executePython(source, { timeout = 8000, signal = null } = {}) {
+  async executePython(source, { timeout = null, signal = null } = {}) {
+    if (timeout !== null && (!Number.isFinite(timeout) || timeout <= 0)) {
+      throw new RangeError('Python execution timeout must be positive or null')
+    }
     if (signal?.aborted) throw abortError(signal)
-    const commandBytes = this.repl.execInputBytes
-      ? this.repl.execInputBytes(source)
-      : new TextEncoder().encode(`exec(${JSON.stringify(source)})\r\n`).length
-    const inputLimit = this.repl.inputMaxBytes || 511
-    if (commandBytes <= inputLimit) {
-      return this.repl.execPy(source, { timeout, signal })
-    }
-    if (!this.hasFeature('file.write.binary') || !this.hasFeature('script.run')) {
-      throw new Error(
-        `Python source requires ${commandBytes} REPL bytes, above the firmware limit ${inputLimit}; ` +
-        'upgrade firmware with file.write.binary and script.run support.',
-      )
-    }
-
-    const path = `/.__espvision_exec_${Date.now().toString(36)}_${this.sequence}.py`
-    let primaryError = null
-    let cleanupError = null
-    let output = null
-    this._diagnostic('python.execute.chunked', { path, sourceBytes: new TextEncoder().encode(source).length, commandBytes })
+    const operation = createOperationDeadline(signal, timeout)
+    signal = operation.signal
     try {
-      const result = await this.runScript(path, source, { timeout, signal, inlineCompletion: true })
-      output = result.output
-    } catch (error) {
-      primaryError = error
-    } finally {
-      if (primaryError) await this.stopForRepl().catch(() => false)
+      if (signal?.aborted) throw abortError(signal)
+      const commandBytes = this.repl.execInputBytes
+        ? this.repl.execInputBytes(source)
+        : new TextEncoder().encode(`exec(${JSON.stringify(source)})\r\n`).length
+      const inputLimit = this.repl.inputMaxBytes || 511
+      if (commandBytes <= inputLimit) {
+        const result = await this.runScript(null, source, {
+          timeout: null, signal, inlineSource: true,
+        })
+        return result.output
+      }
+      if (!this.hasFeature('file.write.binary') || !this.hasFeature('script.run')) {
+        throw new Error(
+          `Python source requires ${commandBytes} REPL bytes, above the firmware limit ${inputLimit}; ` +
+          'upgrade firmware with file.write.binary and script.run support.',
+        )
+      }
+
+      const path = `/.__espvision_exec_${Date.now().toString(36)}_${this.sequence}.py`
+      let primaryError = null
+      let cleanupError = null
+      let output = null
+      this._diagnostic('python.execute.chunked', { path, sourceBytes: new TextEncoder().encode(source).length, commandBytes })
       try {
-        await this.repl.removeFile(path)
+        const result = await this.runScript(path, source, {
+          timeout: null, signal, inlineCompletion: true,
+        })
+        output = result.output
       } catch (error) {
-        cleanupError = error
-        this._diagnostic('python.execute.cleanup_failed', { path, error: error.message })
+        primaryError = error
+      } finally {
+        if (primaryError) await this.stopForRepl().catch(() => false)
+        try {
+          await this.repl.removeFile(path)
+        } catch (error) {
+          cleanupError = error
+          this._diagnostic('python.execute.cleanup_failed', { path, error: error.message })
+        }
       }
+      if (primaryError) throw primaryError
+      if (cleanupError) throw cleanupError
+      return output
+    } finally {
+      operation.dispose()
     }
-    if (primaryError) throw primaryError
-    if (cleanupError) throw cleanupError
-    return output
   }
 
   async interrupt() {
@@ -1344,21 +1379,46 @@ export class DeviceSession {
     return false
   }
 
-  async runScript(path, content, {
+  async runScript(path, content, options = {}) {
+    const timeout = options.timeout === undefined ? 10000 : options.timeout
+    if (timeout !== null && (!Number.isFinite(timeout) || timeout <= 0)) {
+      throw new RangeError('Script timeout must be a positive number or null for an interactive run')
+    }
+    const timeoutError = Object.assign(new Error(`script run timeout after ${timeout}ms`), { code: 'SCRIPT_TIMEOUT' })
+    const operation = createOperationDeadline(options.signal ?? null, timeout, timeoutError)
+    try {
+      return await this._runScript(path, content, {
+        ...options,
+        timeout: null,
+        signal: operation.signal,
+      })
+    } finally {
+      operation.dispose()
+    }
+  }
+
+  async _runScript(path, content, {
     timeout = 10000,
     signal = null,
     onStarted = null,
     maxOutputChars = Number.POSITIVE_INFINITY,
     trial = null,
     inlineCompletion = false,
+    inlineSource = false,
   } = {}) {
     if (signal?.aborted) throw abortError(signal)
-    validateRpcPath(path)
+    if (inlineSource) {
+      if (path !== null || typeof content !== 'string' || inlineCompletion || trial) {
+        throw new TypeError('Inline Python source must run without a device path or typed trial')
+      }
+    } else {
+      validateRpcPath(path)
+    }
     if (inlineCompletion && trial) throw new Error('Typed trial execution cannot use an inline runner')
     if (timeout !== null && (!Number.isFinite(timeout) || timeout <= 0)) {
       throw new RangeError('Script timeout must be a positive number or null for an interactive run')
     }
-    if ((content !== undefined && !this.hasFeature('file.write.binary')) || !this.hasFeature('script.run')) {
+    if (!inlineSource && ((content !== undefined && !this.hasFeature('file.write.binary')) || !this.hasFeature('script.run'))) {
       throw new Error('Running scripts requires script.run and uploading source also requires file.write.binary')
     }
     if (this.runCapture || this.runStarting) {
@@ -1376,11 +1436,27 @@ export class DeviceSession {
       throw error
     }
     this.runStarting = true
+    let inlineSourceVariable = null
+    let inlineSourcePrepared = false
     try {
       if (!await this.stopForRepl({ timeout: timeout === null ? 5000 : Math.min(timeout, 5000), signal })) {
         throw new Error('could not stop the running script (no REPL answer after Ctrl-C)')
       }
-      if (content !== undefined) await this.writeScript(path, content, { signal })
+      if (inlineSource) {
+        inlineSourceVariable = `__evcore_python_${Date.now().toString(36)}_${++this.sequence}`
+        const assignments = this.repl.createInlineSourceAssignments(content, inlineSourceVariable)
+        for (const assignment of assignments) {
+          inlineSourcePrepared = true
+          await this.repl.execPy(assignment, { timeout: INLINE_PYTHON_REPL_TIMEOUT_MS, signal })
+        }
+      } else if (content !== undefined) {
+        await this.writeScript(path, content, { signal })
+      }
+    } catch (error) {
+      if (inlineSourcePrepared) {
+        await this.repl.execPy(`del ${inlineSourceVariable}`, { timeout: 3000 }).catch(() => {})
+      }
+      throw error
     } finally {
       this.runStarting = false
     }
@@ -1427,10 +1503,18 @@ export class DeviceSession {
     completion.catch(() => {})
 
     try {
-      if (inlineCompletion) {
-        const command = this.repl.createScriptRunCommand(path)
+      if (inlineSource) {
+        const command = this.repl.createInlineScriptRunCommand(inlineSourceVariable)
+        await this.repl.writeStdin(command, { signal })
+      } else if (inlineCompletion) {
+        const command = this.repl.createScriptRunCommand(path, { acknowledgeStart: Boolean(onStarted) })
         if (this.repl.scriptRunPrelude) await this.repl.execPy(this.repl.scriptRunPrelude, { timeout: timeout === null ? 5000 : timeout, signal })
-        await this.repl.writeStdin(command)
+        const startAcknowledgement = onStarted
+          ? this.repl.waitForScriptStart({ timeout: SCRIPT_START_ACK_TIMEOUT_MS, signal })
+          : null
+        startAcknowledgement?.catch(() => {})
+        await this.repl.writeStdin(command, { signal })
+        if (startAcknowledgement) await startAcknowledgement
       } else {
         const sentinelLine = this.repl.createScriptEndSentinel()
         const request = { path }
@@ -1440,7 +1524,7 @@ export class DeviceSession {
           request.trial_source_hash = trial.source_hash
         }
         await this.rpc('script.run', request, { timeout: 4000, signal })
-        await this.repl.writeStdin(sentinelLine)
+        await this.repl.writeStdin(sentinelLine, { signal })
       }
       await onStarted?.({ path, trial: trial ? structuredClone(trial) : null })
       return await completion
@@ -1448,7 +1532,7 @@ export class DeviceSession {
       const capture = this.runCapture
       this.runCapture = null
       clearTimeout(capture?.timer)
-      this.repl.cancelScriptEndSentinel()
+      this.repl.cancelScriptEndSentinel(err)
       capture?.reject(err)
       try {
         await completion