dsh-codex-style-computer-use 1.2.3 → 1.3.1

package/lib/core/index.js

@@ -10,7 +10,7 @@
 // {"event":"ready"} announcement.
 
 import { spawn, execFileSync } from 'node:child_process'
-import { createHash } from 'node:crypto'
+import { createHash, randomUUID } from 'node:crypto'
 import { EventEmitter } from 'node:events'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { existsSync, readFileSync, statSync } from 'node:fs'
@@ -22,8 +22,13 @@ const __dirname = fileURLToPath(new URL('.', import.meta.url))
 
 const DEFAULT_TIMEOUT_MS = 15_000
 const CAPTURE_TIMEOUT_MS = 30_000
+// A UIA tree walk can block the resident's synchronous COM thread. Bound the
+// caller's wait separately from recovery of a worker that never returns.
+const UIA_READS = new Set(['uia', 'uiaFromPoint', 'uiaFocused'])
+const URGENT_CONTROL = new Set(['cancelInput', 'abort', 'panic', 'exit', 'endAsk'])
 const INPUT_OPS = new Set(['click', 'shiftClick', 'move', 'drag', 'scroll', 'selectRange',
   'type', 'key', 'uiaAct', 'windowOp', 'activate', 'clipWrite', 'calibrate', 'selftest'])
+const isInputOp = (op, args = {}) => INPUT_OPS.has(op) || (op === 'focus' && args.refocus === true)
 // THE CORE'S ASK DEADLINE, AND IT IS A BARE LITERAL ON PURPOSE (merge-design.md §3, §3.2).
 //
 // It bounds ONE thing: a wedged worker inside `beginAsk`'s raise sequence (a hung UIA provider), or
@@ -48,6 +53,28 @@ export function workerCallError (message, code, op, requestId, outcome = 'unknow
     { code, op, requestId, outcome })
 }
 
+/** A handoff interrupts an input operation, never the authorized task. */
+export function humanContinuation (error = {}) {
+  return {
+    required: true,
+    taskStatus: 'continuing',
+    handback: 'received',
+    nextAction: 'observe-current-target-then-continue-original-task',
+    replayInterruptedInput: false,
+    interruptedOperation: error.op || null,
+    requestId: error.requestId ?? null,
+    outcome: error.outcome === 'not-dispatched' ? 'not-dispatched' : 'unknown',
+    instruction: 'Temporary input interruption only. Control has been handed back. You MUST immediately obtain fresh target evidence, verify any partial effect, and continue the original authorized task from its unfinished step until complete. Do not abandon the task, issue a final wrap-up, or ask for permission to continue because of this handoff. Never blindly replay an interrupted write. Explicit user cancellation, manual pause, or exit still takes precedence.',
+  }
+}
+
+function humanReobserveError (error = {}) {
+  const continuation = humanContinuation(error)
+  return Object.assign(workerCallError(continuation.instruction, 'HUMAN_REOBSERVE',
+    continuation.interruptedOperation, continuation.requestId, continuation.outcome),
+  { transient: true, taskStatus: 'continuing', continuation })
+}
+
 /** Interactive roles that receive Set-of-Marks labels. */
 const SOM_ROLES = new Set([
   'Button', 'MenuItem', 'ListItem', 'TreeItem', 'DataItem', 'TabItem',
@@ -125,6 +152,7 @@ export class ComputerUse extends EventEmitter {
     // bare `Error: spawn UNKNOWN` — no path, no syscall, no Windows code — because NOTHING listened
     // for this child's 'error' event: an unhandled 'error' on an EventEmitter is thrown, so the rich
     // error object (which names the file Windows refused) was discarded on the way out.
+    const child = this.proc
     this.proc.on('error', (e) => {
       let file = '?'
       try { file = `${existsSync(this.workerExe)} exists, ${statSync(this.workerExe).size} bytes` } catch { file = 'stat failed' }
@@ -142,11 +170,11 @@ export class ComputerUse extends EventEmitter {
         const line = buf.slice(0, nl).trim()
         buf = buf.slice(nl + 1)
         if (!line) continue
-        this.onLine(line)
+        if (this.proc === child) this.onLine(line)
       }
     })
     this.proc.stderr.on('data', (d) => this.log(`[worker:stderr] ${d}`))
-    this.proc.on('exit', this.onWorkerExit)
+    this.proc.on('exit', (code) => { if (this.proc === child) this.onWorkerExit(code) })
     return new Promise((resolve, reject) => {
       const t = setTimeout(() => reject(new Error('worker ready timeout')), 10_000)
       // surface the real reason instead of letting the raw emitter error escape
@@ -162,6 +190,7 @@ export class ComputerUse extends EventEmitter {
   onWorkerExit (code) {
     this.ready = false
     this.proc = null
+    this.finishUiaRead(false)
     for (const [id, p] of this.pending) { clearTimeout(p.timer); p.cleanup?.(); p.reject(workerCallError('worker exited', 'worker-exited', p.op, id)) }
     this.pending.clear()
     this.emit('dead', code)
@@ -188,6 +217,14 @@ export class ComputerUse extends EventEmitter {
       this.syncCooperation(msg.cooperation)
       return
     }
+    // Secure-desktop transitions (UAC prompt / lock screen, human request 2026-11-04): the
+    // worker refuses to dispatch while it stands and clears it the moment the normal desktop
+    // returns. Mirror the state so callers can show it, and let the plugin notify the human.
+    if (msg.event === 'secure') {
+      this.secureDesktop = msg.why === 'active'
+      this.emit('secure', msg)
+      return
+    }
     // Durable brake events are separate from automatic physical-input handoff.
     //   panic  — ESC: the human ABORTED. The machine is stopped; wrap up briefly, then wait.
     //   resume — Ctrl+Alt+R: work may continue (a PAUSE ends; it never ends the cycle).
@@ -213,6 +250,7 @@ export class ComputerUse extends EventEmitter {
       this.emit(msg.event, msg)
       return
     }
+    if (this.uiaRead?.id === msg.id) this.finishUiaRead(true)
     const p = this.pending.get(msg.id)
     if (!p) return
     this.pending.delete(msg.id)
@@ -220,8 +258,12 @@ export class ComputerUse extends EventEmitter {
     p.cleanup?.()
     if (msg.data?.cooperation) this.syncCooperation(msg.data.cooperation)
     if (msg.ok) p.resolve(msg.data)
-    else p.reject(workerCallError(msg.error || 'worker error', msg.code || 'worker-refusal-or-error', p.op, msg.id,
-      msg.outcome === 'not-dispatched' ? 'not-dispatched' : 'unknown'))
+    else {
+      const error = workerCallError(msg.error || 'worker error', msg.code || 'worker-refusal-or-error', p.op, msg.id,
+        msg.outcome === 'not-dispatched' ? 'not-dispatched' : 'unknown')
+      if (msg.glowHealth) error.glowHealth = msg.glowHealth
+      p.reject(error.code === 'HUMAN_REOBSERVE' ? humanReobserveError(error) : error)
+    }
   }
 
   /**
@@ -231,12 +273,26 @@ export class ComputerUse extends EventEmitter {
    * @param {boolean} [killOnTimeout] kill a wedged worker when that cap expires (default true)
    * @returns {Promise<any>} worker `data` payload
    */
-  async call (op, args = {}, timeoutMs = DEFAULT_TIMEOUT_MS, killOnTimeout = true) {
-    const signal = INPUT_OPS.has(op) ? this.inputContext.getStore()?.signal : undefined
+  async call (op, args = {}, timeoutMs = DEFAULT_TIMEOUT_MS, killOnTimeout = true, beforeDispatch) {
+    const input = isInputOp(op, args)
+    const context = input ? this.inputContext.getStore() : undefined
+    const signal = context?.signal
     if (signal?.aborted) throw workerCallError('owning tool cancelled', 'INPUT_CANCELLED', op, null, 'not-dispatched')
+    beforeDispatch?.()
+    context?.assertOwnership?.()
     try { await this.ensureWorker() }
     catch (error) { throw workerCallError(error.message || String(error), 'worker-unavailable', op, null, 'not-dispatched') }
+    const child = this.proc
+    if (!child) throw workerCallError('worker exited before dispatch', 'worker-exited', op, null, 'not-dispatched')
+    const queueDeadline = Date.now() + timeoutMs
+    while (this.uiaRead && !URGENT_CONTROL.has(op)) {
+      await this.waitForUiaRead(op, input, signal, queueDeadline)
+      if (this.proc !== child) throw workerCallError('worker exited before dispatch', 'worker-exited', op, null, 'not-dispatched')
+      if (Date.now() >= queueDeadline) throw workerCallError('deadline expired waiting for the UIA read', 'worker-uia-busy', op, null, 'not-dispatched')
+    }
     if (signal?.aborted) throw workerCallError('owning tool cancelled', 'INPUT_CANCELLED', op, null, 'not-dispatched')
+    beforeDispatch?.()
+    context?.assertOwnership?.()
     const id = ++this.seq
     // `__cycle` is this layer's SIGNATURE on a call made on the agent's behalf, and the worker
     // opens (or keeps lit) a computer-use CYCLE only for signed calls. A one-shot
@@ -245,8 +301,12 @@ export class ComputerUse extends EventEmitter {
     // LAST so an op's own args can never forge it.
     const signed = { ...args, __cycle: true }
     signed.__kickoff = this.kickoffRequired
+    // One warning per external call/batch, with a fresh identity for each context.
+    // Never let a caller-supplied argument reuse another tool's announcement.
+    if (input) signed.__inputSeries = this.inputContext.getStore()?.inputSeries || randomUUID()
     return new Promise((resolve, reject) => {
       let written = false
+      const read = UIA_READS.has(op) && killOnTimeout ? (this.uiaRead = { id, child, timedOut: false }) : null
       const cleanup = () => signal?.removeEventListener('abort', abort)
       const abort = () => {
         if (!this.pending.delete(id)) return
@@ -258,6 +318,21 @@ export class ComputerUse extends EventEmitter {
       const timer = setTimeout(() => {
         this.pending.delete(id)
         cleanup()
+        if (read && this.uiaRead === read) {
+          read.timedOut = true
+          this.emit('uia-read-settled', false)
+          // Drop the response by id when it eventually arrives. A later reply for
+          // this id cancels only this watchdog, never a newer worker's deadline.
+          const grace = Math.min(timeoutMs, DEFAULT_TIMEOUT_MS)
+          read.watchdog = setTimeout(() => {
+            if (this.proc !== child || this.uiaRead !== read) return
+            this.log(`[core] UIA read ${id} (${op}) still blocked after ${grace}ms recovery grace; stopping worker pid=${child.pid}`)
+            try { child.kill() } catch { /* already gone */ }
+          }, grace)
+          reject(workerCallError(`UIA observation timed out: ${op} (${timeoutMs}ms); worker still finishing this read. Narrow the tree or use a point query once it returns.`,
+            'worker-timeout', op, id, 'not-dispatched'))
+          return
+        }
         // A CALL THAT RELEASES THE BRAKE MUST NOT BE KILLED FOR BEING SLOW. `proc.kill()` deletes no
         // STOP file (there is no ProcessExit handler in worker.cs; `abort` is Environment.Exit(0) at
         // worker.cs:3045), so killing here would end a question with the brake still up — the exact
@@ -268,18 +343,51 @@ export class ComputerUse extends EventEmitter {
         // UIA/COM provider call blocks its single-threaded loop forever), so kill it and let the NEXT
         // call respawn fresh instead of queueing behind a corpse; pending calls are rejected via
         // onWorkerExit.
-        if (killOnTimeout) { try { this.proc && this.proc.kill() } catch { /* already gone */ } }
+        if (killOnTimeout) { try { if (this.proc === child) child.kill() } catch { /* already gone */ } }
         reject(workerCallError(`worker timeout: ${op} (${timeoutMs}ms)` +
           (killOnTimeout
             ? ' — worker killed, next call respawns'
             : ' — worker left alive so the brake can still be released'),
         'worker-timeout', op, id))
-      }, timeoutMs)
-      this.pending.set(id, { resolve, reject, timer, op, cleanup, abort })
+      }, Math.max(0, queueDeadline - Date.now()))
+      this.pending.set(id, { resolve, reject, timer, op, input, cleanup, abort })
       signal?.addEventListener('abort', abort, { once: true })
       if (signal?.aborted) { abort(); return }
       written = true
-      this.proc.stdin.write(JSON.stringify({ id, op, args: signed }) + '\r\n')
+      child.stdin.write(JSON.stringify({ id, op, args: signed }) + '\r\n')
+    })
+  }
+
+  finishUiaRead (completed) {
+    const read = this.uiaRead
+    if (!read) return
+    this.uiaRead = null
+    clearTimeout(read.watchdog)
+    this.emit('uia-read-settled', completed && !read.timedOut)
+  }
+
+  // Only the stdin reader's cancellation command is out of band. Preserve
+  // emergency/release requests, but never queue ordinary work behind a slow
+  // observation after its caller has given up. Do not replay any request.
+  waitForUiaRead (op, input, signal, deadline) {
+    const busy = () => workerCallError('native UIA observation still busy; this request was not sent',
+      'worker-uia-busy', op, null, 'not-dispatched')
+    if (this.uiaRead.timedOut || Date.now() >= deadline) return Promise.reject(busy())
+    return new Promise((resolve, reject) => {
+      const finish = (error) => {
+        clearTimeout(timer)
+        this.off('uia-read-settled', settled)
+        this.off('input-cancel', cancel)
+        signal?.removeEventListener('abort', cancel)
+        if (error) reject(error); else resolve()
+      }
+      const settled = (completed) => finish(completed ? null : busy())
+      const cancel = () => finish(workerCallError('cancelled before dispatch', 'INPUT_CANCELLED', op, null, 'not-dispatched'))
+      const timer = setTimeout(() => finish(busy()), Math.max(0, deadline - Date.now()))
+      this.once('uia-read-settled', settled)
+      if (input) this.once('input-cancel', cancel)
+      signal?.addEventListener('abort', cancel, { once: true })
+      if (signal?.aborted) cancel()
     })
   }
 
@@ -293,12 +401,17 @@ export class ComputerUse extends EventEmitter {
   // ---------------- screen observation ----------------
   syncCooperation (state) {
     if (!state || Number(state.revision) < Number(this.cooperation.revision)) return
+    if (Number(state.revision) === Number(this.cooperation.revision) && Number.isFinite(state.inputEpoch) &&
+        state.inputEpoch < (this.cooperation.inputEpoch || 0)) return
+    const inputChanged = Number.isFinite(state.inputEpoch) && state.inputEpoch !== (this.cooperation.inputEpoch || 0)
     this.cooperation = state
-    if (state.active) { this.maps.clear(); this.lastMarks = []; this.lastMarkFrame = null }
+    if (state.active || inputChanged) { this.maps.clear(); this.lastMarks = []; this.lastMarkFrame = null }
     this.emit('handoff', state)
   }
 
-  withInputContext (context, fn) { return this.inputContext.run({ signal: context?.signal }, fn) }
+  withInputContext (context, fn) {
+    return this.inputContext.run({ signal: context?.signal, assertOwnership: context?.assertOwnership, inputSeries: randomUUID() }, fn)
+  }
 
   waitForHuman () {
     const signal = this.inputContext.getStore()?.signal
@@ -324,13 +437,13 @@ export class ComputerUse extends EventEmitter {
   async waitInputReady () {
     if (!this.cooperation.active) return
     await this.waitForHuman()
-    throw workerCallError('Human input ended and the three-second quiet interval completed. Observe the current target, then continue this task automatically. Previous coordinates/focus may have changed.',
-      'HUMAN_REOBSERVE', null, null, 'not-dispatched')
+    this.inputContext.getStore()?.assertOwnership?.()
+    throw humanReobserveError({ outcome: 'not-dispatched' })
   }
 
   cancelInputs () {
     this.emit('input-cancel')
-    for (const pending of [...this.pending.values()]) if (INPUT_OPS.has(pending.op)) pending.abort?.()
+    for (const pending of [...this.pending.values()]) if (pending.input || INPUT_OPS.has(pending.op)) pending.abort?.()
   }
 
   /** Raw capture; returns { image: Buffer, mime, region, cursor, settled, settleMs, ts, scaledTo }. */
@@ -463,7 +576,7 @@ export class ComputerUse extends EventEmitter {
    * emergency brake. Called when the agent's turn ends, so a lingering blue border can never
    * claim the machine is still under control after control actually stopped.
    */
-  async calm () { return this.call('calm', {}) }
+  async calm ({ beforeDispatch } = {}) { return this.call('calm', {}, DEFAULT_TIMEOUT_MS, true, beforeDispatch) }
 
   /// **Ask the human one question, machine paused — the ONE question path.**
   ///
@@ -584,7 +697,9 @@ export class ComputerUse extends EventEmitter {
    * the intended target, whether it had to be re-asserted, and an integrity-level warning when
    * Windows (UIPI) would silently discard our input. Text-only — no screenshot needed.
    */
-  async focus (opts = {}) { return this.call('focus', opts) }
+  async focus (opts = {}) {
+    return opts.refocus === true ? this.actuate('focus', opts) : this.call('focus', opts)
+  }
 
   /** Sampled fingerprint plus window identity/geometry; a change invalidates cached marks. */
   async frameSig (opts = {}) { return this.call('frameSig', opts) }
@@ -601,15 +716,21 @@ export class ComputerUse extends EventEmitter {
   async landmarks (opts = {}) {
     const step = opts.step ?? 16
     const insetPct = opts.insetPct ?? 10
+    // UIA-ONLY MODE (test report 2026-11-04): an animated neighbour (DSH Pet) keeps flipping the
+    // sampled pixel signature, so every refresh came back STALE_MARK. uiaOnly pins identity by
+    // window handle / process / geometry alone — the sampled signature is read (for the report)
+    // but never compared; dispatch-time occlusion checking still guards the actual click.
+    const uiaOnly = opts.uiaOnly === true
     const fs = await this.frameSig({ hwnd: opts.hwnd, step, insetPct })
+    if (uiaOnly) fs.sig = null
     const hwnd = fs.hwnd
-    if (!hwnd || !fs.sig) throw staleMark('window snapshot unavailable')
+    if (!hwnd || (!fs.sig && !uiaOnly)) throw staleMark('window snapshot unavailable')
     const cached = this.maps.get(String(hwnd))
-    const key = JSON.stringify([opts.depth ?? 14, opts.maxNodes ?? 1500, opts.maxMarks ?? 80, opts.minSize ?? 8, opts.role, opts.nameContains])
+    const key = JSON.stringify([opts.depth ?? 14, opts.maxNodes ?? 1500, opts.maxMarks ?? 80, opts.minSize ?? 8, opts.role, opts.nameContains, uiaOnly])
     if (cached && sameMarkFrame(cached.frame, fs) && cached.key === key && !opts.refresh) {
       this.lastMarks = cached.marks
       this.lastMarkFrame = { ...fs, step, insetPct }
-      return { hwnd, marks: cached.marks, count: cached.marks.length, reused: true, ageMs: Date.now() - cached.ts, sig: fs.sig }
+      return { hwnd, marks: cached.marks, count: cached.marks.length, reused: true, ageMs: Date.now() - cached.ts, sig: fs.sig, uiaOnly }
     }
     const uia = await this.call('uia', {
       hwnd: hwnd || undefined,
@@ -620,6 +741,7 @@ export class ComputerUse extends EventEmitter {
     })
     const marks = buildMarks(uia.flat || [], opts.maxMarks ?? 80, opts.minSize ?? 8)
     const after = await this.frameSig({ hwnd, step, insetPct })
+    if (uiaOnly) after.sig = null
     if (!sameMarkFrame(fs, after)) {
       const changed = ['hwnd', 'pid'].filter(k => fs[k] !== after[k])
       for (const k of ['x', 'y', 'width', 'height']) if (fs.region?.[k] !== after.region?.[k]) changed.push(`region.${k}`)
@@ -632,7 +754,7 @@ export class ComputerUse extends EventEmitter {
     this.lastMarkFrame = { ...after, step, insetPct }
     this.maps.set(String(hwnd), { marks, frame: after, sig: after.sig, key, ts: Date.now() })
     if (this.maps.size > 16) this.maps.delete(this.maps.keys().next().value)
-    return { hwnd, marks, count: marks.length, reused: false, sig: fs ? fs.sig : null, elements: (uia.flat || []).length }
+    return { hwnd, marks, count: marks.length, reused: false, sig: fs ? fs.sig : null, uiaOnly, elements: (uia.flat || []).length }
   }
 
   // The human's emergency brake, reachable from the model side too (ESC / Ctrl+Alt+Q are
@@ -706,6 +828,8 @@ export class ComputerUse extends EventEmitter {
   }
 
   async clipRead () { return this.call('clipRead', {}) }
+  /** Worker-side OCR: text + per-word boxes in ABSOLUTE screen pixels (2026-11-04). */
+  async ocr (region) { return this.call('ocr', region ? { ...region } : {}) }
   async clipWrite (text) { return this.actuate('clipWrite', { text }) }
 
   async activateWindow (sel) { return this.actuate('activate', sel) }
@@ -763,10 +887,23 @@ export class ComputerUse extends EventEmitter {
       if (err.code === 'HUMAN_YIELD') {
         // The hook's event can arrive just after its operation refusal. One cheap local
         // status read closes that race; waiting spends no model requests and never replays input.
-        await this.call('ping', {})
-        await this.waitForHuman()
-        err.code = 'HUMAN_REOBSERVE'
-        err.message += ' Human input is now idle for at least three seconds. Inspect the current target and continue automatically; do not repeat any partial write without a readback.'
+        try {
+          await this.call('ping', {})
+          await this.waitForHuman()
+          this.inputContext.getStore()?.assertOwnership?.()
+          err = humanReobserveError({ ...err, op })
+        } catch (waitError) {
+          // Cancelling the local wait cannot erase input already accepted before handoff.
+          err = workerCallError(waitError.message || String(waitError), waitError.code || 'handoff-wait-failed',
+            op, err.requestId ?? null, err.outcome === 'not-dispatched' ? 'not-dispatched' : 'unknown')
+        }
+      }
+      if (err.code === 'HUMAN_REOBSERVE') {
+        try { this.inputContext.getStore()?.assertOwnership?.() }
+        catch (ownerError) {
+          err = workerCallError(ownerError.message, ownerError.code || 'COMPUTER_OWNER_CHANGED', op,
+            err.requestId ?? null, err.outcome)
+        }
       }
       rec.error = String(err.message || err)
       throw err
@@ -782,8 +919,13 @@ function staleMark (reason) {
 }
 
 function sameMarkFrame (a, b) {
-  return !!a?.sig && a.sig === b?.sig && a.hwnd === b.hwnd && a.pid === b.pid &&
-    ['x', 'y', 'width', 'height'].every(k => Number.isFinite(a.region?.[k]) && a.region[k] === b.region?.[k])
+  const identity = a?.hwnd === b?.hwnd && a?.pid === b?.pid &&
+    ['x', 'y', 'width', 'height'].every(k => Number.isFinite(a.region?.[k]) && a.region[k] === b.region[k])
+  if (!identity) return false
+  // A uiaOnly landmark frame (sig === null, test report 2026-11-04) deliberately carries no
+  // pixel signature: identity is geometry alone, and the click path's occlusion check remains.
+  if (a.sig === null) return true
+  return !!a?.sig && a.sig === b?.sig
 }
 
 /** Keep secrets out of the audit log. */

package/lib/core/native-runtime.js

@@ -13,7 +13,12 @@ const framework = env => path.join(env.SystemRoot || env.windir || 'C:\\Windows'
 export function workerReferences (env = process.env) {
   const gac = path.join(env.SystemRoot || env.windir || 'C:\\Windows', 'Microsoft.NET', 'assembly', 'GAC_MSIL')
   return ['System.dll', 'System.Core.dll', 'System.Drawing.dll', 'System.Web.Extensions.dll', 'System.Windows.Forms.dll',
-    ...['UIAutomationClient', 'UIAutomationTypes', 'WindowsBase'].map(name => path.join(gac, name, 'v4.0_4.0.0.0__31bf3856ad364e35', `${name}.dll`))]
+    ...['UIAutomationClient', 'UIAutomationTypes', 'WindowsBase'].map(name => path.join(gac, name, 'v4.0_4.0.0.0__31bf3856ad364e35', `${name}.dll`)),
+    // Inbox OCR (2026-11-04): the legacy csc cannot compose the split WinMetadata winmds, so the
+    // union Windows.winmd ships inside the package and the WinRT interop pieces come from the OS.
+    path.join(framework(env), 'System.Runtime.dll'),
+    path.join(gac, 'System.Runtime.WindowsRuntime', 'v4.0_4.0.0.0__b77a5c561934e089', 'System.Runtime.WindowsRuntime.dll'),
+    path.join(import.meta.dirname, 'winmd', 'Windows.winmd')]
 }
 
 export function compileNativeBinary (source, output, references, { env = process.env } = {}) {