@esp-vision/device-core 0.1.0 → 0.2.0

package/tests/test-device-functional-checks.mjs

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile, mkdtemp, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { parseArgs } from './hardware-check.mjs'
+import { DEVICE_CHECKS, parseCheckResult, runDeviceChecks, saveJpeg } from './device-checks.mjs'
+
+function devicePeer({ results = {}, board = 'TEST', screenFails = false } = {}) {
+  const files = new Map(), calls = [], listeners = new Map()
+  return {
+    calls, files, listeners,
+    async inspect({ fields }) { calls.push(['inspect', fields]); return { identity: { board, firmwareVersion: 'test' }, capabilities: { protocol: { evMuxVersion: 4 }, features: [] }, runtime: { vmReady: true } } },
+    files: Object.assign(files, {
+      async list() { return [...files.keys()].map(path => ({ path })) },
+      async write({ path, data, overwrite }) { calls.push(['write', path]); assert.equal(overwrite, false); files.set(path, data) },
+      async remove({ path }) { calls.push(['remove', path]); files.delete(path) },
+    }),
+    python: { async execute({ source }) {
+      calls.push(['execute', source])
+      const name = /\['run_check'\]\("([a-z_]+)"/.exec(source)?.[1]
+      if (!name) return { ok: true, output: '' }
+      const result = results[name] ?? { name, status: 'PASS', data: { width: 240, height: 320 } }
+      if (name === 'preview' && result.status === 'PASS' && !results.noPreview) listeners.get('preview')?.({ data: new Uint8Array([1]) })
+      return { ok: true, output: `unrelated output\n__EVDEVICECHECK__${JSON.stringify(result)}\n` }
+    } },
+    on(event, listener) { listeners.set(event, listener); return () => listeners.delete(event) },
+    async capture({ source }) {
+      calls.push(['capture', source])
+      if (source === 'screen' && screenFails) throw Object.assign(new Error('Not supported'), { code: 'UNSUPPORTED_OPERATION' })
+      return { data: new Uint8Array([255, 216, 0, 255, 217]), mimeType: 'image/jpeg', metadata: { width: 240, height: 320 } }
+    },
+  }
+}
+
+test('functional CLI preserves all legacy checks, validates options and honors explicit screenshot request', () => {
+  assert.deepEqual(parseArgs(['--tcp', 'test', '--checks', 'all']).checks, DEVICE_CHECKS)
+  assert.equal(parseArgs(['--tcp', 'test', '--checks', 'all']).timeout, 600000)
+  assert.equal(parseArgs(['--tcp', 'test', '--checks', 'all', '--timeout', '5000']).timeout, 5000)
+  assert.deepEqual(parseArgs(['--serial', 'test', '--screen-output', 'screen.jpg']).checks, ['display'])
+  for (const args of [['--checks', 'bogus'], ['--frames', '0'], ['--framesize', 'QVGA;print(1)'], ['--quality', '101'], ['--frame-timeout', '0'], ['--display-hold', '-1']]) assert.throws(() => parseArgs(['--tcp', 'test', ...args]))
+})
+
+test('device check reports reject stale, duplicated and malformed markers', () => {
+  const valid = '__EVDEVICECHECK__{"name":"memory","status":"PASS","data":{"heapFree":1}}'
+  assert.equal(parseCheckResult(valid, 'memory').data.heapFree, 1)
+  for (const output of ['', valid + '\n' + valid, '__EVDEVICECHECK__bad', valid.replace('memory', 'camera'), valid.replace('PASS', 'UNKNOWN')]) assert.throws(() => parseCheckResult(output, 'memory'), { code: 'CHECK_REPORT_INVALID' })
+})
+
+test('functional checks stage their shared fixture once and consume preview via public events', async () => {
+  const device = devicePeer(), reports = []
+  await runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'memory,preview,orientation']), { nonce: 'abc123', report: value => reports.push(value) })
+  assert.equal(device.calls.filter(call => call[0] === 'write').length, 1)
+  assert.equal(device.files.size, 0)
+  assert.equal(device.listeners.size, 0)
+  assert.equal(reports.find(result => result.check === 'preview').data.received, 1)
+  assert.deepEqual(reports.at(-1), { check: 'summary', passed: 3, failed: 0, skipped: 0 })
+})
+
+test('required IPA never silently skips; a failed check does not suppress later checks', async () => {
+  const device = devicePeer({ board: 'ESP32_P4X_EYE', results: { ipa_stats: { name: 'ipa_stats', status: 'SKIP', error: { message: 'ESP_ERR_NOT_SUPPORTED' } } } }), reports = []
+  await assert.rejects(runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'ipa_stats,identity']), { nonce: 'abc123', report: value => reports.push(value) }), { code: 'DEVICE_CHECKS_FAILED' })
+  assert.equal(reports.find(result => result.check === 'ipa_stats').status, 'FAIL')
+  assert.equal(reports.find(result => result.check === 'identity').status, 'PASS')
+  assert.equal(device.files.size, 0)
+})
+
+test('missing LCD skips ordinary display tests but explicitly requested screenshot must fail', async () => {
+  const response = { name: 'display', status: 'SKIP', error: { message: 'ESP_ERR_NOT_SUPPORTED' } }
+  for (const explicit of [false, true]) {
+    const device = devicePeer({ results: { display: response } }), reports = []
+    const options = parseArgs(['--tcp', 'test', '--checks', 'display', ...(explicit ? ['--screen-output', 'screen.jpg'] : [])])
+    const run = runDeviceChecks(device, options, { nonce: 'abc123', report: value => reports.push(value) })
+    if (explicit) await assert.rejects(run, { code: 'DEVICE_CHECKS_FAILED' })
+    else await run
+    assert.equal(reports.find(result => result.check === 'display').status, explicit ? 'FAIL' : 'SKIP')
+    assert.ok(device.calls.some(call => call[0] === 'execute' && call[1].includes("['close_display']()")))
+  }
+})
+
+test('screen JPEG is captured while display fixture is alive and saved on host', async () => {
+  const directory = await mkdtemp(join(tmpdir(), 'esp-vision-screen-'))
+  const output = join(directory, 'screen.jpg'), device = devicePeer()
+  try {
+    await runDeviceChecks(device, parseArgs(['--tcp', 'test', '--checks', 'display', '--screen-output', output]), { nonce: 'abc123', report() {} })
+    assert.deepEqual(await readFile(output), Buffer.from([255, 216, 0, 255, 217]))
+    const captureAt = device.calls.findIndex(call => call[0] === 'capture' && call[1] === 'screen')
+    const closeAt = device.calls.findIndex(call => call[0] === 'execute' && call[1].includes("['close_display']()"))
+    assert.ok(captureAt > 0 && closeAt > captureAt)
+    assert.equal(device.files.size, 0)
+  } finally { await rm(directory, { recursive: true, force: true }) }
+})
+
+test('truncated JPEG and missing dimensions are refused before host artifact is written', async () => {
+  await assert.rejects(saveJpeg({ data: new Uint8Array([255, 216]), mimeType: 'image/jpeg', metadata: { width: 1, height: 1 } }), { code: 'CAPTURE_INVALID' })
+  await assert.rejects(saveJpeg({ data: new Uint8Array([255, 216, 255, 217]), mimeType: 'image/jpeg' }), { code: 'CAPTURE_INVALID' })
+})

package/tests/test-device-hardware-cli.mjs

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer } from 'node:net'
+import { once } from 'node:events'
+import { checkHardware, parseArgs, serialTransport } from './hardware-check.mjs'
+import { EvMuxParser, makeEvMuxFrame } from '../src/evmux.js'
+import { EV_MUX_REQUIRED_FEATURES, EV_MUX_REQUIRED_CHANNELS, EV_MUX_DEFAULT_LIMITS } from '../src/device_session.js'
+
+test('hardware CLI validates transport, timeout and never accepts credential URLs', () => {
+  assert.equal(parseArgs(['--tcp', 'localhost']).port, 3232)
+  assert.equal(parseArgs(['--serial', '/dev/test', '--role', 'usb']).role, 'usb')
+  assert.equal(parseArgs(['--tcp', '[::1]:1234', '--write']).host, '::1')
+  for (const args of [[], ['--tcp', 'a', '--serial', 'b'], ['--tcp', 'tcp://user:secret@host'], ['--tcp', 'a:65536'], ['--serial', 'a', '--timeout', 'NaN'], ['--tcp', 'a', '--role', 'usb']]) assert.throws(() => parseArgs(args))
+})
+
+test('default hardware acceptance exercises real facade over a fake EV-MUX TCP peer', async () => {
+  const sessionId = 'a'.repeat(32), methods = [], sockets = new Set(), messages = []
+  const server = createServer(socket => {
+    sockets.add(socket)
+    socket.on('close', () => sockets.delete(socket))
+    const parser = new EvMuxParser({ filterFrame(metadata, bytes) {
+      const text = new TextDecoder().decode(bytes)
+      if (metadata.channel === 'repl.stdin') {
+        const marker = /EV_HARDWARE_[a-z0-9]+/.exec(text)?.[0] ?? 'EVIDE_BOOT_OK'
+        socket.write(makeEvMuxFrame({ channel: 'repl.stdout', type: 'data', sessionId, vmEpoch: 1, payload: `${text}\r\n${marker}\r\n>>> ` }))
+        return false
+      }
+      if (!metadata.channel.endsWith('.rpc')) return false
+      methods.push(metadata.method)
+      const request = JSON.parse(text)
+      let result = { ok: true }
+      if (metadata.method === 'hello') result = { ok: true, evMuxVersion: 4, deviceId: 'abcdef123456', hostname: 'esp-vision-test', board: 'TEST', firmware: { version: 'test' }, vmReady: true, session: { id: sessionId, vmEpoch: 1, leaseMs: 15000, keepaliveMs: 5000 } }
+      if (metadata.method === 'capabilities') result = { ok: true, protocol: { evMuxVersion: 4 }, features: EV_MUX_REQUIRED_FEATURES, channels: EV_MUX_REQUIRED_CHANNELS, limits: { ...EV_MUX_DEFAULT_LIMITS, txLargePayloadMax: 262144 }, session: { policy: 'firstCome', leaseMs: 15000, keepaliveMs: 5000 } }
+      socket.write(makeEvMuxFrame({ channel: metadata.channel, type: 'rsp', method: metadata.method, seq: metadata.seq, ...((metadata.method !== 'capabilities' && (metadata.method !== 'hello' || request.acquire)) ? { sessionId, vmEpoch: 1 } : {}), payload: JSON.stringify(result) }))
+      return false
+    } })
+    socket.on('data', bytes => parser.feedBytes(bytes))
+  })
+  server.listen(0, '127.0.0.1')
+  await once(server, 'listening')
+  try {
+    await checkHardware(parseArgs(['--tcp', `127.0.0.1:${server.address().port}`, '--timeout', '5000']), { nonce: 'abc123', report: value => messages.push(value) })
+    assert.deepEqual(messages.map(value => value.check), ['inspect', 'python'])
+    assert.ok(methods.includes('session.release'))
+    assert.ok(!methods.includes('script.write'))
+    assert.ok(!methods.includes('network.configure'))
+  } finally { for (const socket of sockets) socket.destroy(); await new Promise(resolve => server.close(resolve)) }
+})
+
+function fakeDevice({ mismatch = false, collision = false, writeFails = false } = {}) {
+  const calls = [], files = new Map(), path = '/evhc_abc123.bin'
+  if (collision) files.set(path, new Uint8Array([7]))
+  return {
+    calls, files,
+    async connect() { calls.push('connect') },
+    async inspect() { return { identity: { board: 'TEST' }, network: { password: 'NEVER_PRINT' } } },
+    python: { async execute() { return { ok: true, output: 'EV_HARDWARE_abc123\n' } } },
+    files: Object.assign(files, {
+      async list() { return [...files.keys()].map(path => ({ path })) },
+      async write({ path, data, overwrite }) { calls.push('write'); assert.equal(overwrite, false); files.set(`${path}.tmp`, data); if (writeFails) throw new Error('Write failed'); files.delete(`${path}.tmp`); files.set(path, data) },
+      async read({ path }) { return mismatch ? new Uint8Array([0]) : files.get(path) },
+      async remove({ path, signal }) { assert.equal(signal.aborted, false); calls.push('remove'); files.delete(path) },
+    }),
+    async disconnect() { calls.push('disconnect') },
+  }
+}
+
+test('write acceptance validates bytes and deletes only its owned file, even after partial failure', async () => {
+  for (const config of [{}, { mismatch: true }, { writeFails: true }]) {
+    const device = fakeDevice(config), reports = []
+    const run = checkHardware(parseArgs(['--tcp', 'localhost', '--write']), { device, nonce: 'abc123', report: value => reports.push(value) })
+    if (config.mismatch || config.writeFails) await assert.rejects(run)
+    else await run
+    assert.equal(device.files.size, 0)
+    assert.equal(device.calls.at(-1), 'disconnect')
+    assert.ok(device.calls.includes('remove'))
+    assert.ok(!JSON.stringify(reports).includes('NEVER_PRINT'))
+  }
+})
+
+test('write acceptance refuses an existing test path and preserves it', async () => {
+  const device = fakeDevice({ collision: true })
+  await assert.rejects(checkHardware(parseArgs(['--tcp', 'localhost', '--write']), { device, nonce: 'abc123', report() {} }), { code: 'TEST_PATH_EXISTS' })
+  assert.equal(device.files.size, 1)
+  assert.deepEqual(device.calls, ['connect', 'disconnect'])
+})
+
+test('cancellation before connection has no file side effects and still disconnects', async () => {
+  const device = fakeDevice(), controller = new AbortController()
+  controller.abort()
+  await assert.rejects(checkHardware(parseArgs(['--tcp', 'localhost']), { device, signal: controller.signal, report() {} }), { code: 'CANCELLED' })
+  assert.equal(device.files.size, 0)
+  assert.equal(device.calls.at(-1), 'disconnect')
+})
+
+test('missing optional Python executable fails cleanly without opening a port', async () => {
+  const transport = serialTransport({ python: '/nonexistent-esp-vision-python', serial: '/not-a-device' })
+  const unsubscribe = transport.subscribe({ error() {}, close() {} })
+  try {
+    await assert.rejects(transport.connect({ signal: AbortSignal.timeout(1000) }), { code: 'SERIAL_ERROR' })
+  } finally { unsubscribe(); await transport.disconnect() }
+})

package/tests/test-device-operations-api.mjs

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: Apache-2.0
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { createDeviceOperations } from '../src/device_operations.js'
+
+function fixture({ enabled = true, features = ['network.background', 'network.configure', 'debug.capture_frame', 'device.control', 'storage.writer.lease'] } = {}) {
+  const calls = []
+  let operation = null
+  let sequence = 0
+  const state = {}
+  const session = {
+    identity: { deviceId: '123', hostname: 'esp-vision-test' }, capabilities: { features }, vmReady: true, vmEpoch: 1,
+    hasFeature: feature => features.includes(feature), snapshot: () => ({ state: 'ready' }),
+    async networkStatus(opts) { calls.push(['status', opts]); return { enabled, operation } },
+    async configureNetwork(credentials, opts) { calls.push(['configure', credentials, opts]); enabled = true; operation = { id: String(++sequence), state: 'succeeded' }; return { accepted: true, operationId: operation.id } },
+    async setNetworkEnabled(value, opts) { calls.push(['enable', value, opts]); enabled = value; operation = { id: String(++sequence), state: 'succeeded' }; return { accepted: true, operationId: operation.id } },
+    async forgetNetwork(opts) { calls.push(['forget', opts]); enabled = false; operation = { id: String(++sequence), state: 'succeeded' }; return { accepted: true, operationId: operation.id } },
+    async rpc(method, payload, opts) { calls.push(['rpc', method, payload, opts]); return { ok: true } },
+    async control(command, opts) { calls.push(['control', command, opts]); return { ok: true } },
+    async captureImage(method, payload, opts) { calls.push(['capture', method, payload, opts]); return { data: new Uint8Array([255, 216]), mimeType: 'image/jpeg', metadata: { seq: 1 } } },
+  }
+  return { session, state, calls, api: createDeviceOperations({ session, state }) }
+}
+
+test('inspect returns only requested fields and never invokes REPL', async () => {
+  const { api, state, calls, session } = fixture()
+  state.run = { path: '/app.py', completion: 'start', status: 'running', done: Promise.resolve() }
+  const result = await api.inspect({ fields: ['identity', 'runtime', 'storage'] })
+  assert.deepEqual(Object.keys(result), ['identity', 'runtime', 'storage'])
+  assert.equal(result.runtime.run.status, 'running')
+  assert.equal(result.runtime.run.done, undefined)
+  result.identity.hostname = 'changed'
+  assert.equal(session.identity.hostname, 'esp-vision-test')
+  assert.deepEqual(calls.map(call => call[2]?.volume), ['flash', 'sd'])
+  await assert.rejects(api.inspect({ fields: ['unknown'] }), /fields/)
+})
+
+test('credentials update preserves omitted enabled state after asynchronous operation completes', async () => {
+  const { api, calls, state } = fixture({ enabled: false })
+  const result = await api.configure({ network: { credentials: { ssid: 'test', password: '' } } })
+  assert.equal(result.network.enabled, false)
+  assert.deepEqual(result.completed.map(step => step.action), ['network.configure', 'network.enable'])
+  assert.deepEqual(calls.filter(call => call[0] === 'enable').map(call => call[1]), [false])
+  assert.equal(state.operation, null)
+})
+
+test('credential clearing disables networking; enabling preserves credentials', async () => {
+  const { api, calls } = fixture()
+  const result = await api.configure({ network: { credentials: null } })
+  assert.equal(result.network.enabled, false)
+  assert.equal(calls.filter(call => call[0] === 'forget').length, 1)
+  await api.configure({ network: { enabled: true } })
+  assert.equal(calls.filter(call => call[0] === 'configure').length, 0)
+})
+
+test('configuration rejects unknown, contradictory and invalid inputs before mutation', async () => {
+  const { api, calls } = fixture()
+  for (const request of [
+    { other: true }, { network: {} }, { network: { enabled: 'yes' } },
+    { network: { credentials: null, enabled: true } },
+    { network: { credentials: { ssid: '', password: '' } } },
+    { network: { credentials: { ssid: 'a', password: '', hidden: true } } },
+    { network: { credentials: { ssid: '你'.repeat(11), password: '' } } },
+  ]) await assert.rejects(api.configure(request))
+  assert.equal(calls.length, 0)
+})
+
+test('configuration failure reports completed steps without pretending to roll back credentials', async () => {
+  const { api, session, state } = fixture({ enabled: false })
+  session.setNetworkEnabled = async () => { throw Object.assign(new Error('enable failed'), { code: 'OFFLINE' }) }
+  await assert.rejects(api.configure({ network: { credentials: { ssid: 'test', password: 'secret12' } } }), error => {
+    assert.equal(error.code, 'OFFLINE')
+    assert.deepEqual(error.completed.map(step => step.action), ['network.configure'])
+    assert.ok(!JSON.stringify(error).includes('secret12'))
+    return true
+  })
+  assert.equal(state.operation, null)
+})
+
+test('configuration cancellation records accepted pending operation and releases local lock', async () => {
+  const { api, session, state } = fixture()
+  const controller = new AbortController()
+  session.setNetworkEnabled = async () => { controller.abort(new Error('cancelled')); return { accepted: true, operationId: 'pending' } }
+  await assert.rejects(api.configure({ network: { enabled: false }, signal: controller.signal }), error => {
+    assert.match(error.message, /cancelled/)
+    assert.equal(error.pending.operationId, 'pending')
+    assert.deepEqual(error.completed, [])
+    return true
+  })
+  assert.equal(state.operation, null)
+})
+
+test('control maps explicit commands, validates mode and can interrupt Python but not file writes', async () => {
+  const { api, calls, state } = fixture()
+  state.operation = { kind: 'python.execute' }
+  await api.control({ action: 'stop' })
+  await api.control({ action: 'reset', mode: 'soft' })
+  await api.control({ action: 'reset', mode: 'hard' })
+  await api.control({ action: 'bootloader' })
+  assert.deepEqual(calls.map(call => call[0] === 'rpc' ? call[2].action : call[1]), ['stop', 'soft-reset', 'hard-reset', 'bootloader'])
+  state.operation = { kind: 'files.write' }
+  await assert.rejects(api.control({ action: 'reset', mode: 'hard' }), error => error.code === 'DEVICE_BUSY')
+  await assert.rejects(api.control({ action: 'reset' }), /mode/)
+  await assert.rejects(api.control({ action: 'stop', mode: 'hard' }), /mode/)
+})
+
+test('capture returns binary JPEG, forwards quality and never substitutes camera for unsupported screen', async () => {
+  const { api, calls, state } = fixture()
+  const image = await api.capture({ source: 'camera', format: 'jpeg', quality: 80 })
+  assert.deepEqual(image.data, new Uint8Array([255, 216]))
+  assert.equal(calls[0][1], 'debug.capture_frame')
+  assert.deepEqual(calls[0][2], { quality: 80 })
+  await assert.rejects(api.capture({ source: 'screen' }), error => error.code === 'UNSUPPORTED_OPERATION')
+  await assert.rejects(api.capture({ source: 'camera', quality: 101 }), /quality/)
+  await assert.rejects(api.capture({ source: 'camera', format: 'png' }), /jpeg/)
+  assert.equal(calls.length, 1)
+  assert.equal(state.operation, null)
+})
+
+test('capture errors release operation lock and pre-abort performs no IO', async () => {
+  const { api, session, state, calls } = fixture()
+  session.captureImage = async () => { throw Object.assign(new Error('camera failed'), { code: 'CAPTURE_FAILED' }) }
+  await assert.rejects(api.capture({ source: 'camera' }), error => error.code === 'CAPTURE_FAILED')
+  assert.equal(state.operation, null)
+  const controller = new AbortController(); controller.abort()
+  await assert.rejects(api.capture({ source: 'camera', signal: controller.signal }), error => error.name === 'AbortError')
+  assert.equal(calls.length, 0)
+})
+
+
+test('configuration accepts firmware-supported PSKs and rejects invalid passwords locally', async () => {
+  const { api, calls } = fixture()
+  for (const password of ['short', '你'.repeat(8), 'g'.repeat(64)]) {
+    await assert.rejects(api.configure({ network: { credentials: { ssid: 'test', password } } }), /password/)
+  }
+  assert.equal(calls.length, 0)
+  await api.configure({ network: { credentials: { ssid: 'test', password: 'a'.repeat(64) } } })
+  assert.equal(calls.filter(call => call[0] === 'configure').length, 1)
+})
+
+test('accepted asynchronous failure preserves operation identity and never applies later steps', async () => {
+  const { api, session, calls, state } = fixture({ enabled: false })
+  let polls = 0
+  session.networkStatus = async () => ++polls === 1 ? { enabled: false } : {
+    enabled: false, operation: { id: '1', state: 'failed', error: { code: 'AUTH_FAILED', message: 'Authentication failed' } },
+  }
+  await assert.rejects(api.configure({ network: { credentials: { ssid: 'test', password: 'password' }, enabled: true } }), error => {
+    assert.equal(error.code, 'AUTH_FAILED')
+    assert.deepEqual(error.completed, [])
+    assert.equal(error.pending.operationId, '1')
+    return true
+  })
+  assert.equal(calls.filter(call => call[0] === 'enable').length, 0)
+  assert.equal(state.operation, null)
+})
+
+test('capture and configuration honor a busy device without transmitting requests', async () => {
+  const { api, state, calls } = fixture()
+  state.operation = { kind: 'files.write' }
+  await assert.rejects(api.capture({ source: 'camera' }), error => error.code === 'DEVICE_BUSY')
+  await assert.rejects(api.configure({ network: { enabled: false } }), error => error.code === 'DEVICE_BUSY')
+  assert.equal(calls.length, 0)
+})
+
+
+test('control reserves the device until acknowledgement so file work cannot race a reset', async () => {
+  const { api, session, state } = fixture()
+  let release
+  session.control = () => new Promise(resolve => { release = resolve })
+  const resetting = api.control({ action: 'reset', mode: 'hard' })
+  assert.equal(state.operation.kind, 'control')
+  await assert.rejects(api.capture({ source: 'camera' }), error => error.code === 'DEVICE_BUSY')
+  release({ ok: true })
+  await resetting
+  assert.equal(state.operation, null)
+})
+
+test('configuration snapshots credentials and enabled before waiting for device status', async () => {
+  const { api, session, calls } = fixture()
+  const original = session.networkStatus
+  let release
+  let first = true
+  session.networkStatus = opts => {
+    if (!first) return original(opts)
+    first = false
+    return new Promise(resolve => { release = () => original(opts).then(resolve) })
+  }
+  const request = { network: { credentials: { ssid: 'initial', password: '' }, enabled: true } }
+  const configuring = api.configure(request)
+  request.network.credentials.ssid = 'changed'
+  request.network.credentials.password = 'bad'
+  request.network.enabled = false
+  release()
+  const result = await configuring
+  assert.equal(result.network.enabled, true)
+  assert.deepEqual(calls.find(call => call[0] === 'configure')[1], { ssid: 'initial', password: '' })
+})
+
+
+test('malformed network acknowledgements cannot be reported as completed configuration', async () => {
+  const { api, session } = fixture()
+  for (const response of [{ ok: true }, { accepted: false, operationId: '1' }, { accepted: true }]) {
+    session.setNetworkEnabled = async () => response
+    await assert.rejects(api.configure({ network: { enabled: false } }), error => {
+      assert.equal(error.code, 'INVALID_RESPONSE')
+      assert.deepEqual(error.completed, [])
+      return true
+    })
+  }
+})

package/tests/test-device-python-api.mjs

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { createPythonApi } from '../src/device_python.js'
+import { createFilesApi } from '../src/device_files.js'
+
+function fixture() {
+  const calls = [], state = {}
+  const session = {
+    repl: { writeStdin: async data => calls.push(['input', data]), removeFile: async path => calls.push(['remove', path]) },
+    executePython: async (source, options) => { calls.push(['source', source, options]); return '42\r\n' },
+    runScript: async (path, content, options) => { calls.push(['run', path, content, options]); return { ok: true, output: 'existing', outputTruncated: false } },
+    writeFile: async () => { throw new Error('Unexpected write') },
+  }
+  return { session, state, calls, python: createPythonApi({ session, state }) }
+}
+
+test('source wait and path wait return the same result shape without rewriting path', async () => {
+  const { python, calls } = fixture()
+  assert.deepEqual(await python.execute({ source: 'print(42)' }), { ok: true, path: null, output: '42\n', outputTruncated: false })
+  assert.deepEqual(await python.execute({ path: '/existing.py' }), { ok: true, path: '/existing.py', output: 'existing', outputTruncated: false })
+  assert.deepEqual(calls[1].slice(0, 3), ['run', '/existing.py', undefined])
+  assert.equal(calls[1][3].inlineCompletion, true)
+})
+
+test('execution rejects ambiguous input, unsupported modes, unsafe paths and invalid deadlines before I/O', async () => {
+  const { python, calls } = fixture()
+  for (const request of [{}, { source: '', path: '/a.py' }, { source: 0 }, { path: '../a.py' }, { path: '/a/../b.py' }, { source: '', completion: 'other' }, { source: '', timeout: 0 }, { source: '', completion: 'start', timeout: 3 }]) {
+    await assert.rejects(python.execute(request))
+  }
+  assert.equal(calls.length, 0)
+})
+
+test('pre-aborted execution never starts Python', async () => {
+  const { python, calls } = fixture()
+  await assert.rejects(python.execute({ source: '', signal: AbortSignal.abort() }), { name: 'AbortError' })
+  assert.equal(calls.length, 0)
+})
+
+test('existing script start preserves the file and permits terminal input while rejecting parallel work', async () => {
+  const { python, calls, session, state } = fixture()
+  let finish
+  session.startScript = async (path, content, options) => {
+    assert.equal(options.inlineCompletion, true)
+    calls.push(['start', path, content])
+    return { done: new Promise(resolve => { finish = resolve }) }
+  }
+  const handle = await python.execute({ path: '/model-demo.py', completion: 'start' })
+  assert.deepEqual(calls[0], ['start', '/model-demo.py', undefined])
+  assert.equal(state.run.status, 'running')
+  await python.input('hello\r')
+  await assert.rejects(python.execute({ source: 'pass' }), { code: 'DEVICE_BUSY' })
+  const files = createFilesApi({ session, state })
+  await assert.rejects(files.write({ path: '/other', data: 'x' }), { code: 'DEVICE_BUSY' })
+  finish({ ok: true, output: '', outputTruncated: false })
+  await handle.done
+  assert.equal(state.run, null)
+  assert.equal(state.operation, null)
+  assert.ok(!calls.some(call => call[0] === 'remove'))
+})
+
+test('started source uses a private temporary file and removes it only after completion', async () => {
+  const { python, calls, session } = fixture()
+  let finish
+  session.startScript = async (path, content, options) => {
+    assert.equal(options.inlineCompletion, true)
+    calls.push(['start', path, content])
+    return { done: new Promise(resolve => { finish = resolve }) }
+  }
+  const handle = await python.execute({ source: 'while True: pass', completion: 'start' })
+  assert.match(handle.path, /^\/\.__evcore_.*\.py$/)
+  assert.equal(calls.length, 1)
+  assert.equal(calls[0][2], 'while True: pass')
+  finish({ ok: true, output: 'done' })
+  assert.equal((await handle.done).output, 'done')
+  assert.deepEqual(calls.at(-1), ['remove', handle.path])
+})
+
+test('execution failures release the operation and retain the original error', async () => {
+  const { python, session, state } = fixture()
+  const failure = Object.assign(new Error('disconnected'), { code: 'SESSION_REQUIRED' })
+  session.startScript = async () => { throw failure }
+  session.repl.removeFile = async () => { throw new Error('cleanup also failed') }
+  await assert.rejects(python.execute({ source: 'pass', completion: 'start' }), error => error === failure)
+  assert.equal(state.run, null)
+  assert.equal(state.operation, null)
+})
+
+test('terminal input is excluded during startup and automated execution', async () => {
+  const { python, session } = fixture()
+  let finish
+  session.executePython = async () => new Promise(resolve => { finish = resolve })
+  const execution = python.execute({ source: 'pass' })
+  await assert.rejects(python.input('oops'), { code: 'DEVICE_BUSY' })
+  finish('')
+  await execution
+  await python.input(new Uint8Array([13]))
+  await assert.rejects(python.input({}), TypeError)
+})
+
+
+test('source execution honors the same output bound as path execution', async () => {
+  const { python } = fixture()
+  assert.deepEqual(await python.execute({ source: 'print(42)', maxOutputChars: 1 }), { ok: true, path: null, output: '4', outputTruncated: true })
+})
+
+test('interactive script input receives only user data, never the completion marker command', async () => {
+  const { DeviceSession } = await import('../src/device_session.js')
+  const { EvMuxParser, makeEvMuxFrame } = await import('../src/evmux.js')
+  const { EvRepl } = await import('../src/evrepl.js')
+  const input = [], methods = []
+  let session, waitingForInput = false
+  const stdout = payload => session.feedBytes(makeEvMuxFrame({
+    channel: 'repl.stdout', type: 'data', sessionId: session.sessionId, vmEpoch: session.vmEpoch, payload,
+  }))
+  const parser = new EvMuxParser({ filterFrame(metadata, bytes) {
+    const text = new TextDecoder().decode(bytes)
+    if (metadata.channel === 'repl.signal') return
+    if (metadata.channel === 'repl.stdin') {
+      if (waitingForInput) {
+        input.push(text)
+        waitingForInput = false
+        stdout(`${text}\r\nreceived:${text.trim()}\r\n${session.repl.scriptEndMarker}\r\n>>> `)
+      } else if (text.includes('/interactive.py')) {
+        waitingForInput = true
+        stdout(`${text}\r\nNAME?`)
+      } else stdout(`${text}\r\n>>> `)
+      return
+    }
+    methods.push(metadata.method)
+    // Legacy script.run deliberately models input() consuming the next stdin line.
+    if (metadata.method === 'script.run') waitingForInput = true
+    session.feedBytes(makeEvMuxFrame({ channel: metadata.channel, type: 'rsp', method: metadata.method, seq: metadata.seq,
+      sessionId: session.sessionId, vmEpoch: session.vmEpoch, payload: JSON.stringify({ ok: true }),
+    }))
+  } })
+  session = new DeviceSession({ transport: { async writeBytes(bytes) { parser.feedBytes(bytes) } }, EvMuxParser, makeEvMuxFrame, EvRepl })
+  session.state = 'ready'; session.sessionId = 'a'.repeat(32); session.vmEpoch = 1; session.vmReady = true
+  session.capabilities = { features: ['script.run', 'device.control'] }
+  try {
+    const python = createPythonApi({ session, state: {} })
+    const run = await python.execute({ path: '/interactive.py', completion: 'start', maxOutputChars: 1024 })
+    assert.deepEqual(input, [], 'Core must not pre-fill the application input with its private completion command')
+    assert.equal(waitingForInput, true)
+    await python.input('ev-api-check\r')
+    const result = await run.done
+    assert.deepEqual(input, ['ev-api-check\r'])
+    assert.match(result.output, /received:ev-api-check/)
+    assert.ok(!methods.includes('script.write'), 'Existing scripts must never be overwritten')
+  } finally { session.close() }
+})
+
+test('Python requests reject unknown parameters and malformed signals before interpreter I/O', async () => {
+  const { python, calls } = fixture()
+  for (const signal of [{}, true, 'signal', { aborted: false, addEventListener() {}, removeEventListener() {} }]) {
+    await assert.rejects(python.execute({ source: 'pass', signal }), TypeError)
+  }
+  await assert.rejects(python.execute({ source: 'pass', mode: 'wait' }), /Unknown Python execution parameter/)
+  await assert.rejects(python.execute({ source: 'pass', [Symbol('option')]: true }), /Unknown Python execution parameter/)
+  assert.equal(calls.length, 0)
+})
+
+test('Python snapshots request getters and input byte buffers', async () => {
+  const { python, session } = fixture()
+  let reads = 0
+  await python.execute({ get source() { reads++; return reads === 1 ? 'safe' : 'changed' } })
+  assert.equal(reads, 1)
+  let release, observed
+  session.repl.writeStdin = async data => {
+    await new Promise(resolve => { release = resolve })
+    observed = Array.from(data)
+  }
+  const data = new Uint8Array([65])
+  const writing = python.input(data)
+  data[0] = 66
+  release()
+  await writing
+  assert.deepEqual(observed, [65])
+})
+
+test('disconnect and cleanup errors retain execution failure and always release shared state', async () => {
+  const { python, session, state } = fixture()
+  const original = Object.assign(new Error('transport closed during execution'), { code: 'SESSION_REQUIRED' })
+  let rejectDone
+  session.startScript = async () => ({ done: new Promise((_resolve, reject) => { rejectDone = reject }) })
+  session.stopForRepl = async () => { throw new Error('cleanup transport closed') }
+  const run = await python.execute({ source: 'pass', completion: 'start' })
+  const failed = assert.rejects(run.done, error => error === original)
+  rejectDone(original)
+  await failed
+  assert.equal(state.operation, null)
+  assert.equal(state.run, null)
+  assert.equal(await python.execute({ source: '1' }).then(result => result.ok), true)
+})