dsh-labscript 0.2.7 → 0.3.0

package/lib/tools.js

@@ -30,6 +30,9 @@ function progressLine(run) {
   if (run.kind) parts.push('kind=' + run.kind)
   if (run.n_h5 !== undefined) parts.push('h5=' + run.n_h5 + '/' + (run.expected_n_shots || '?'))
   else if (run.expected_n_shots) parts.push('expected=' + run.expected_n_shots)
+  // h5 counts files; labscript writes each file before compiling it, so a compiled
+  // but not yet executed run shows h5>0 until the first acquisition data appears.
+  if (run.n_executed !== undefined) parts.push('executed=' + run.n_executed)
   if (run.complete !== undefined) parts.push('complete=' + run.complete)
   if (run.elapsed_s !== undefined) parts.push('elapsed=' + run.elapsed_s + 's')
   return parts.join('  ')
@@ -64,14 +67,21 @@ function globalLines(args, value) {
   return out
 }
 
+// runmanager decides the shot count from the expansion settings, which runmanager.remote
+// cannot read: a tuple is not an axis and an array can be switched to expansion "none".
+// The panel's n_shots is therefore the only authoritative number; this line is a hint.
 function scanLine(value) {
   const axes = value.scan_axes && typeof value.scan_axes === 'object' ? value.scan_axes : {}
   const names = Object.keys(axes).sort()
   const product = value.n_shots_from_arrays
-  const mismatch = typeof product === 'number' && typeof value.n_shots === 'number' && value.n_shots !== product
+  const known = typeof value.n_shots === 'number'
+  const mismatch = typeof product === 'number' && known && value.n_shots !== product
   if (names.length === 0 && !mismatch) return ''
   const detail = names.length ? names.map((key) => key + '=' + axes[key]).join(', ') : 'none'
-  return 'scan axes: ' + detail + '  n_shots_from_arrays=' + product + (mismatch ? '  (panel n_shots=' + value.n_shots + ' differs)' : '')
+  const verdict = mismatch
+    ? '  product ' + product + ' != n_shots ' + value.n_shots + ': n_shots is authoritative (a tuple global or an expansion setting of none is not an axis)'
+    : '  product ' + product + '  n_shots ' + (known ? value.n_shots : '?') + ' (authoritative)'
+  return 'scan axes (heuristic): ' + detail + verdict
 }
 
 function resultsLine(value) {
@@ -82,6 +92,24 @@ function resultsLine(value) {
   return 'results: ' + names.map((group) => group + ' (' + layout[group].length + ' fields)').join(', ')
 }
 
+// Protocol keys that the loaded labscript does not define, with the closest names it
+// does define: a renamed panel global is the most common reason a protocol is stale.
+function nameCheckDetail(check) {
+  const missing = check && Array.isArray(check.missing) ? check.missing : []
+  return missing.map((key) => {
+    const suggestions = (check.suggestions || {})[key] || []
+    return key + (suggestions.length ? ' (closest: ' + suggestions.join(', ') + ')' : '')
+  }).join(', ')
+}
+
+function nameCheckLine(value) {
+  const check = value.name_check
+  if (!check) return ''
+  if (check.checked === false) return 'script key check: not checked (' + (check.reason || 'no script') + ')'
+  const detail = nameCheckDetail(check)
+  return detail ? 'script key check: MISSING ' + detail : ''
+}
+
 function dataGlobalsLines(args, value) {
   const globals = value.globals
   if (!globals) return []
@@ -166,23 +194,57 @@ async function requireApproval(runtime, exec, toolName, reason, approvalKey) {
   }
 }
 
+// The pending run may be stored under either path form: labs_engage returns the
+// mapped folder, the bridge also reports the raw runmanager folder, and an agent may
+// quote either one back.
+function pendingFolders(pending) {
+  if (!pending) return []
+  return [pending.run_folder, pending.mapped_run_folder, pending.remote_run_folder].filter((folder) => Boolean(folder))
+}
+
+function isPendingRun(pending, folder) {
+  return pendingFolders(pending).includes(folder)
+}
+
+// Returns the dropped run description when a dead submission was cleared.
 async function clearStalePending(runtime, exec) {
   const pending = runtime.state.pending
-  if (!pending) return
+  if (!pending) return null
   if (pending.run_folder) {
+    let progress = null
     try {
-      const progress = await runtime.runBridge('progress', {
+      progress = await runtime.runBridge('progress', {
         run_folder: pending.run_folder,
         expected_n_shots: pending.expected_n_shots,
       }, { signal: exec.signal })
-      if (!progress.complete) {
-        throw new LabError('RUN_PENDING', 'a run is still in progress (' + progress.n_h5 + '/' + progress.expected_n_shots + ' shots): call labs_wait first, or labs_abort')
+    } catch {
+      progress = null
+    }
+    if (progress && progress.complete !== true) {
+      const ageS = pending.submitted_at ? Math.round((Date.now() - Date.parse(pending.submitted_at)) / 1000) : 0
+      const staleS = Number((runtime.config.engage || {}).staleS || 180)
+      const nH5 = Number(progress.n_h5 || 0)
+      if (progress.folder_exists && nH5 === 0 && ageS >= staleS) {
+        // Nothing was ever written for this submission and it is minutes old: the
+        // compilation aborted, so the run folder stays empty forever. Drop it and
+        // report the drop instead of refusing to submit again.
+        const dropped = {
+          run_folder: progress.mapped_run_folder || pending.run_folder,
+          age_s: ageS,
+          expected_n_shots: pending.expected_n_shots,
+        }
+        runtime.clearPending()
+        return dropped
       }
-    } catch (error) {
-      if (error instanceof LabError && error.code === 'RUN_PENDING') throw error
+      const next = nH5 === 0
+        ? ' A submission with no shots is dropped automatically after ' + staleS + ' s, or call labs_abort now.'
+        : ' Call labs_wait to inspect it, or labs_abort to abandon it.'
+      throw new LabError('RUN_PENDING', 'a run is still in progress (' + nH5 + '/' + (pending.expected_n_shots || '?') +
+        ' shots, ' + ageS + ' s old):' + next)
     }
   }
   runtime.clearPending()
+  return null
 }
 
 function mockApprovalSkipped(runtime) {
@@ -193,7 +255,7 @@ export function registerTools(ctx, runtime) {
 
   ctx.tools.register({
     name: 'labs_status',
-    description: 'Read the labscript runmanager panel: loaded labscript, globals (evaluated; raw expressions with raw=true), n_shots, error_in_globals, run_shots, shot output folder, pending run progress, and the panel snapshot directory. Read-only; call this before any write. Pass keys=[...] (leaf global names; UI group names are not globals) to print the selected panel values (240 chars each; raw=true prints the raw expression), missing keys are shown as <missing>; keys=["*"] prints every global. scan axes lists array-valued globals (their lengths multiply to n_shots_from_arrays) and a differing panel n_shots is flagged. The shot output folder is the folder the NEXT run will use; it does not exist until engage. Paths in the output are already mapped for this machine through pathMap; do not map them again.',
+    description: 'Read the labscript runmanager panel: loaded labscript, globals (evaluated; raw expressions with raw=true), n_shots, error_in_globals, run_shots, shuffle, shot output folder (called run folder in this tool: where the NEXT engage writes its shot files; it does not exist until engage), pending run progress, and the panel snapshot directory. Read-only; call this before any write. Pass keys=[...] (leaf global names; UI group names are not globals) to print the selected panel values (240 chars each; raw=true prints the raw expression), missing keys are shown as <missing> (the global is in an inactive group or misspelled); keys=["*"] prints every global. scan axes is a heuristic: it counts array-valued globals and their lengths multiply to n_shots_from_arrays, but runmanager does not expand tuples and an expansion setting of none turns an array into a non-axis, neither of which is visible from the remote API. n_shots is authoritative: when the two differ, report n_shots and say that at least one array-valued global is not an axis. shuffle true means shot order does not follow the axis order. Paths in the output are already mapped for this machine through pathMap; do not map them again.',
     parameters: {
       type: 'object',
       properties: {
@@ -207,7 +269,7 @@ export function registerTools(ctx, runtime) {
       'backend: ' + value.backend + '  plugin: v' + runtime.version,
       'labscript: ' + value.labscript,
       'shot output: ' + value.shot_output_folder,
-      'n_shots: ' + value.n_shots + '  error_in_globals: ' + value.error_in_globals + '  run_shots: ' + value.run_shots,
+      'n_shots: ' + value.n_shots + '  error_in_globals: ' + value.error_in_globals + '  run_shots: ' + value.run_shots + '  shuffle: ' + (value.shuffle === undefined || value.shuffle === null ? 'unknown' : value.shuffle),
       progressLine(value.last_run),
       'panel history: ' + (value.panel_history ? value.panel_history.dir + ' (' + value.panel_history.count + ' snapshots)' : 'n/a'),
       scanLine(value),
@@ -227,13 +289,13 @@ export function registerTools(ctx, runtime) {
 
   ctx.tools.register({
     name: 'labs_set',
-    description: 'Write runmanager panel globals. values are JSON scalars (bool/number/string); pass raw=true to write expression strings, or reps=N to write the repetition counter (np.arange(N)). A full panel snapshot is taken before the write. Does not run anything.',
+    description: 'Write runmanager panel globals. One call can do the whole step: values are JSON scalars (bool/number/string); with raw=true a string value is written as an expression (e.g. np.arange(0.5, 6.7, 0.2)) while bool/number values are still converted normally (true -> True, 2.72 -> 2.72), so scalars, an expression scan axis and reps=N can be combined. reps=N writes the configured repetition global as np.arange(N). A list global becomes a scan axis only if runmanager actually expands it (a tuple is passed through whole, and an expansion setting of none drops the axis). A global name must not shadow a Python builtin or a name from "from labscript import *": runmanager accepts the name, labscript fails at compile time, and that failure is visible only in runmanager output tab. A full panel snapshot is taken before the write. Does not run anything.',
     parameters: {
       type: 'object',
       properties: {
         values: { type: 'object', additionalProperties: true, description: 'Panel globals to write: key -> scalar' },
-        raw: { type: 'boolean', description: 'values are raw expression strings (e.g. np.arange(0, 8, 0.3))' },
-        reps: { type: 'integer', minimum: 1, description: 'Write the configured repetition global as np.arange(reps)' },
+        raw: { type: 'boolean', description: 'String values are written as expressions; bool/number values are still converted (mix them freely with reps=N)' },
+        reps: { type: 'integer', minimum: 1, description: 'Also write the configured repetition global as np.arange(reps)' },
         note: { type: 'string', description: 'One sentence: what this batch is for (written to the event log)' },
       },
       required: ['values'],
@@ -257,7 +319,7 @@ export function registerTools(ctx, runtime) {
 
   ctx.tools.register({
     name: 'labs_engage',
-    description: 'Submit the current panel for a run (compiles and sends to BLACS). Returns immediately with run_folder, n_shots_at_submit and expected_n_shots; use labs_wait later to wait for completion. Refuses when error_in_globals is true or another run is still pending.',
+    description: 'Submit the current panel as one sequence: runmanager writes one shot file per point and hands it to BLACS (this is the "shot output folder", called run_folder in this tool). Returns immediately with run_folder, n_shots_at_submit and expected_n_shots; use labs_wait later to wait for completion. It cannot see compilation errors: runmanager shows those only in its output tab. Refuses when error_in_globals is true or another run is still pending; a pending run that produced no shot at all for config.engage.staleS (default 180 s) is dropped and reported as dropped_stale_pending.',
     parameters: {
       type: 'object',
       properties: {
@@ -267,29 +329,33 @@ export function registerTools(ctx, runtime) {
     },
     isConcurrencySafe: () => false,
     output: looseOutput((_args, value) => text(lines([
+      value.dropped_stale_pending ? 'dropped stale pending run: ' + value.dropped_stale_pending.run_folder + ' (' + value.dropped_stale_pending.age_s + ' s old, no shots ever appeared)' : '',
       'submitted run: ' + (value.mapped_run_folder || value.run_folder || '<run folder pending>'),
       'n_shots_at_submit: ' + value.n_shots_at_submit + '  expected: ' + value.expected_n_shots,
       'call labs_wait when results are needed.',
     ]))),
     async execute(args, exec) {
       return runtime.serial(async () => {
-        await clearStalePending(runtime, exec)
+        const dropped = await clearStalePending(runtime, exec)
         const before = await runtime.runBridge('status', {}, { signal: exec.signal })
         await requireApproval(runtime, exec, 'labs_engage', 'Submit a labscript run: ' + (before.labscript || '<script>') + ', n_shots=' + before.n_shots + ', backend=' + before.backend, 'engage')
         const data = await runtime.runBridge('engage', { note: args.note }, { signal: exec.signal, timeoutMs: 180000 })
         runtime.setLastRun({
-          run_folder: data.run_folder,
+          run_folder: data.mapped_run_folder || data.run_folder,
+          remote_run_folder: data.run_folder,
           expected_n_shots: data.expected_n_shots,
           submitted_at: data.submitted_at,
         })
         runtime.setPending({
           kind: 'engage',
-          run_folder: data.run_folder,
+          run_folder: data.mapped_run_folder || data.run_folder,
+          remote_run_folder: data.run_folder,
           expected_n_shots: data.expected_n_shots,
           submitted_at: data.submitted_at,
           note: args.note,
           snapshot: null,
         })
+        if (dropped) data.dropped_stale_pending = dropped
         return data
       })
     },
@@ -297,7 +363,7 @@ export function registerTools(ctx, runtime) {
 
   ctx.tools.register({
     name: 'labs_wait',
-    description: 'Wait for the pending run to finish (blocking, timeout in seconds). If the pending run came from labs_protocol run, this call also finalizes it: postprocess, finish write-back of panel and calibration history, and panel restore. Returns expected vs actual shots and, for protocols, the postprocess/finish/restore results. A run folder that does not exist and is not the pending run of this session fails immediately instead of waiting.',
+    description: 'Wait for the pending run (sequence) to finish (blocking, timeout in seconds). If it came from labs_protocol run, this call also finalizes it: postprocess, finish write-back of panel and calibration history, and panel restore. Returns expected vs actual shot files and, for protocols, the postprocess/finish/restore results. Returns early with diagnosis no_shots or compile_stalled when no shot file appeared for config.engage.noShotS seconds (default 25): compilation errors are visible only in runmanager output tab, which this tool cannot read, so report exactly that and ask the operator to paste the tab; call labs_wait again only if you expect a slow compile. diagnosis compiled_not_executed means shot files exist but BLACS acquired no data: BLACS may be paused, may have refused the shot because its connection table is not a subset of the lab connection table, or a device group failed to program within 5 minutes (the queue then pauses and puts the shot back at its head) - all visible only in the BLACS GUI. More shot files than expected means the panel n_shots changed after submit, or BLACS Repeat all / Repeat last re-ran shots. A run folder that does not exist and is not the pending run of this session fails immediately instead of waiting.',
     parameters: {
       type: 'object',
       properties: {
@@ -312,7 +378,7 @@ export function registerTools(ctx, runtime) {
       'run: ' + (value.mapped_run_folder || value.run_folder),
       value.aborted ? 'wait cancelled by labs_abort (run aborted)' : '',
       value.folder_exists === false ? 'folder: missing' : '',
-      'shots: ' + value.n_h5 + '/' + (value.expected_n_shots || '?') + '  complete: ' + value.complete + (value.timed_out ? '  TIMED OUT' : '') + (value.diagnosis ? '  diagnosis: ' + value.diagnosis : ''),
+      'shots: ' + value.n_h5 + '/' + (value.expected_n_shots || '?') + ' h5 files' + (value.n_executed !== undefined ? ', ' + value.n_executed + ' with acquisition data' : '') + '  complete: ' + value.complete + (value.timed_out ? '  TIMED OUT' : '') + (value.diagnosis ? '  diagnosis: ' + value.diagnosis : ''),
       value.hint ? 'hint: ' + value.hint : '',
       value.finalize && value.finalize.postprocess ? 'postprocess: ' + JSON.stringify(value.finalize.postprocess).slice(0, 400) : '',
       value.finalize && value.finalize.finish ? 'finish: ' + JSON.stringify(value.finalize.finish).slice(0, 300) : '',
@@ -323,8 +389,9 @@ export function registerTools(ctx, runtime) {
         const pending = runtime.state.pending
         const runFolder = args.run_folder || (pending ? pending.run_folder : '')
         if (!runFolder) throw new LabError('NO_PENDING_RUN', 'no run folder: submit with labs_engage or labs_protocol run first, or pass run_folder')
-        const expected = pending && pending.run_folder === runFolder ? pending.expected_n_shots : undefined
-        if (!(pending && pending.run_folder === runFolder)) {
+        const pendingRun = isPendingRun(pending, runFolder)
+        const expected = pendingRun ? pending.expected_n_shots : undefined
+        if (!pendingRun) {
           let probe = null
           try {
             probe = await runtime.runBridge('progress', {
@@ -368,6 +435,7 @@ export function registerTools(ctx, runtime) {
           run_folder: waited.run_folder,
           expected_n_shots: waited.expected_n_shots,
           n_h5: waited.n_h5,
+          n_executed: waited.n_executed,
           complete: waited.complete,
           timed_out: waited.timed_out,
           elapsed: waited.elapsed,
@@ -378,13 +446,13 @@ export function registerTools(ctx, runtime) {
           folder_exists: waited.folder_exists,
         }
         for (const key of Object.keys(out)) if (out[key] === undefined) delete out[key]
-        if (waited.complete && runtime.state.lastRun && runtime.state.lastRun.run_folder === runFolder) {
+        if (waited.complete && runtime.state.lastRun && isPendingRun(runtime.state.lastRun, runFolder)) {
           runtime.setLastRun(Object.assign({}, runtime.state.lastRun, {
             completed_at: new Date().toISOString(),
             n_h5: waited.n_h5,
           }))
         }
-        if (waited.complete && pending && pending.kind === 'protocol' && pending.run_folder === runFolder) {
+        if (waited.complete && pending && pending.kind === 'protocol' && pendingRun) {
           const finalize = await runtime.runBridge('protocol_finalize', {
             protocol: pending.plan,
             run_folder: runFolder,
@@ -393,7 +461,7 @@ export function registerTools(ctx, runtime) {
           }, { signal: exec.signal, timeoutMs: 180000 })
           out.finalize = finalize
           runtime.clearPending()
-        } else if (waited.complete && pending && pending.run_folder === runFolder) {
+        } else if (waited.complete && pending && pendingRun) {
           runtime.clearPending()
         }
         return out
@@ -422,7 +490,7 @@ export function registerTools(ctx, runtime) {
 
   ctx.tools.register({
     name: 'labs_data',
-    description: 'Read a run folder HDF5: first-shot globals (pass keys=[...] to print selected values, ["*"] for all), the results groups with results: true, and with scan: a per-shot scan axis summary (unique points, min/max, median step) plus the numeric result columns; pass limit to print up to 20 raw rows. Read-only. run_folder defaults to the pending run, else the last run submitted through this plugin (persisted across restarts); for a historical run pass its folder explicitly. A missing folder is an error: runmanager\'s shot output is the NEXT run folder and only exists after engage.',
+    description: 'Read a run folder (shot output folder) HDF5: first-shot globals (pass keys=[...] to print selected values, ["*"] for all), the results groups with results: true, and with scan: a per-shot axis summary (unique points, min/max, median step) plus the numeric result columns; pass limit to print up to 20 raw rows. Each shot file holds the evaluated globals of that shot, its hardware commands and, after execution, images/ and results/ - a shot with no images/results was not executed. With shuffle on, read each shot\'s parameters from its own file instead of assuming axis order. Read-only. run_folder defaults to the pending run, else the last run submitted through this plugin (persisted across restarts); for a historical run pass its folder explicitly. A missing folder is an error: the shot output folder is the NEXT sequence\'s folder and only exists after engage.',
     parameters: {
       type: 'object',
       properties: {
@@ -479,8 +547,8 @@ export function registerTools(ctx, runtime) {
       value.plan && value.plan.scan ? 'scan: ' + Object.keys(value.plan.scan).join(', ') : '',
       value.hard_limits ? 'hard limits: ' + JSON.stringify(value.hard_limits).slice(0, 240) : '',
       value.warnings && value.warnings.length ? 'warnings: ' + value.warnings.join('; ') : '',
-      value.name_check && value.name_check.checked && value.name_check.missing && value.name_check.missing.length ? 'script key check: MISSING ' + value.name_check.missing.join(', ') : '',
-      value.name_check && value.name_check.checked === false ? 'script key check: not checked (' + (value.name_check.reason || 'no script') + ')' : '',
+      nameCheckLine(value),
+      value.dropped_stale_pending ? 'dropped stale pending run: ' + value.dropped_stale_pending.run_folder + ' (' + value.dropped_stale_pending.age_s + ' s old, no shots ever appeared)' : '',
       value.engage ? 'submitted: ' + (value.engage.mapped_run_folder || value.engage.run_folder || '<run folder pending>') + '  n_shots_at_submit: ' + value.n_shots_at_submit : '',
       value.engage ? 'call labs_wait to finalize this protocol.' : '',
     ]))),
@@ -496,38 +564,39 @@ export function registerTools(ctx, runtime) {
         return { name: loaded.name, file: loaded.file, warnings: loaded.warnings.concat(planned.warnings || []), plan: planned.plan, hard_limits: planned.hard_limits, name_check: planned.name_check }
       }
       return runtime.serial(async () => {
-        await clearStalePending(runtime, exec)
+        const dropped = await clearStalePending(runtime, exec)
         const planned = await runtime.runBridge('protocol_plan', { protocol: loaded.plan }, { signal: exec.signal })
         if (planned.hard_limits && planned.hard_limits.checked) {
           // plan command already fails on violations; nothing to do
         }
         const nameCheck = planned.name_check
-        if (nameCheck && nameCheck.checked && nameCheck.missing && nameCheck.missing.length) {
-          const detail = nameCheck.missing.map((key) => {
-            const suggestions = (nameCheck.suggestions || {})[key] || []
-            return key + (suggestions.length ? ' (closest: ' + suggestions.join(', ') + ')' : '')
-          }).join(', ')
-          await requireApproval(runtime, exec, 'labs_protocol', 'Protocol ' + loaded.name + ' uses key(s) that are not in the currently loaded labscript: ' + detail + '. Continue anyway?', 'protocolNames')
+        const missingDetail = nameCheckDetail(nameCheck)
+        if (missingDetail) {
+          await requireApproval(runtime, exec, 'labs_protocol', 'Protocol ' + loaded.name + ' uses key(s) that are not in the currently loaded labscript: ' + missingDetail + '. Continue anyway?', 'protocolNames')
         }
         await requireApproval(runtime, exec, 'labs_protocol', 'Run protocol ' + loaded.name + ': expected ' + planned.plan.expected_n_shots + ' shots, labscript ' + (loaded.plan.labscript || loaded.plan.joint_script) + ', backend ' + runtime.config.backend, 'protocolRun')
         const started = await runtime.runBridge('protocol_start', { protocol: loaded.plan, note: args.note }, { signal: exec.signal, timeoutMs: 180000 })
         if (started.engage) {
           runtime.setLastRun({
-            run_folder: started.engage.run_folder,
+            run_folder: started.engage.mapped_run_folder || started.engage.run_folder,
+            remote_run_folder: started.engage.run_folder,
             expected_n_shots: started.expected_n_shots,
             submitted_at: started.submitted_at,
           })
           runtime.setPending({
             kind: 'protocol',
             plan: loaded.plan,
-            run_folder: started.engage.run_folder,
+            run_folder: started.engage.mapped_run_folder || started.engage.run_folder,
+            remote_run_folder: started.engage.run_folder,
             expected_n_shots: started.expected_n_shots,
             snapshot: started.snapshot,
             submitted_at: started.submitted_at,
             note: args.note,
           })
         }
-        return Object.assign({ name: loaded.name, file: loaded.file, warnings: loaded.warnings.concat(planned.warnings || []), name_check: nameCheck }, started)
+        const out = Object.assign({ name: loaded.name, file: loaded.file, warnings: loaded.warnings.concat(planned.warnings || []), name_check: nameCheck }, started)
+        if (dropped) out.dropped_stale_pending = dropped
+        return out
       })
     },
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-labscript",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Control labscript-suite experiments from DeepSeek Harness: runmanager globals and scans, submits and waits, YAML fixed-operation protocols with postprocess write-back, panel snapshots, a built-in mock backend and a read-only doctor.",
   "type": "module",
   "main": "lib/index.js",