dsh-labscript 0.2.0 → 0.2.2

package/lib/skill.js

@@ -1,60 +1,60 @@
-/**
- * Runtime skill: workflow rules for controlling a labscript-suite experiment.
- * Tool descriptions carry parameter detail; this skill carries the order of
- * operations and the stop rules.
- */
-export const SKILL_CONTENT = [
-  '# Labscript experiment control',
-  '',
-  'You control a labscript-suite experiment through the labs_* tools. The panel state,',
-  'not your memory, is the truth. Never guess a global value or a scan axis.',
-  '',
-  '## Before any write',
-  '1. Call labs_status. Confirm the loaded labscript, n_shots, error_in_globals, run_shots',
-  '   and the keys you are about to touch.',
-  '2. Real hardware: the user must approve this turn before panel writes, engage or abort.',
-  '   The plugin asks for its own one-shot approval on engage/protocol run in the real',
-  '   backend; that approval does not replace the user conversation requirement.',
-  '3. Prefer a fixed protocol (labs_protocol) for stable calibration flows. Use labs_set',
-  '   and labs_engage only for exploratory measurements.',
-  '',
-  '## Running',
-  '- labs_set writes the panel. It does not run anything. Always pass note: one sentence',
-  '  saying what this batch is for (it is written to the event log).',
-  '- labs_engage submits a run and returns immediately with n_shots_at_submit and',
-  '  expected_n_shots. Do not poll in a loop; when the user wants results, call labs_wait.',
-  '  After submitting you may end the turn or do independent work.',
-  '- labs_protocol run submits a fixed protocol; labs_wait finalizes it (postprocess,',
-  '  finish write-back, panel restore).',
-  '- backend defaults to mock-labscript; real hardware is only used when the config says',
-  '  backend: labscript explicitly.',
-  '- On a new install or when a tool fails with a configuration error, run labs_doctor first.',
-  '- labs_abort stops compiling/submitting new shots; shots already queued in BLACS or',
-  '  running are not stopped. It is not a hardware interlock. Never call it unless',
-  '  something looks wrong or the user asks.',
-  '- A panel snapshot is taken before every write. labs_restore restores only the keys that',
-  '  write touched (pass full=true for the whole panel), so concurrent edits elsewhere are kept.',
-  '',
-  '## Reading results',
-  '- labs_data reads the run folder HDF5: globals of the first shot and, with scan: a',
-  '  per-shot table. HDF5 is authoritative; the panel is only intermediate state.',
-  '- Report facts: run folder, expected vs actual shots, postprocess numbers, warnings.',
-  '  If a number is missing, say so instead of inventing one.',
-  '',
-  '## Stop rules',
-  '- error_in_globals true: fix or ask; never engage.',
-  '- wait timed out or diagnosis=compiled_not_executed: the shots may be compiled but BLACS',
-  '  may be paused/not executing. Check BLACS and the panel, then abort or ask; do not resubmit blindly.',
-  '- A run is already pending: wait or abort before submitting another.',
-].join(String.fromCharCode(10))
-
-export function registerSkill(ctx) {
-  ctx.skills.register({
-    name: 'labscript',
-    description: 'Control a labscript-suite experiment through the labs_* tools: read the runmanager panel, write globals and scans, submit runs without blocking, wait for completion, run YAML fixed-operation protocols with postprocess write-back, read run HDF5 data, restore panel snapshots.',
-    whenToUse: 'When the user asks to inspect or change the labscript panel, run shots or scans, run a fixed experiment protocol, or read results of a labscript run.',
-    source: 'runtime',
-    content: SKILL_CONTENT,
-    invocation: { modelInvocable: true, userInvocable: true },
-  })
-}
+/**
+ * Runtime skill: workflow rules for controlling a labscript-suite experiment.
+ * Tool descriptions carry parameter detail; this skill carries the order of
+ * operations and the stop rules.
+ */
+export const SKILL_CONTENT = [
+  '# Labscript experiment control',
+  '',
+  'You control a labscript-suite experiment through the labs_* tools. The panel state,',
+  'not your memory, is the truth. Never guess a global value or a scan axis.',
+  '',
+  '## Before any write',
+  '1. Call labs_status. Confirm the loaded labscript, n_shots, error_in_globals, run_shots',
+  '   and the keys you are about to touch.',
+  '2. Real hardware: the user must approve this turn before panel writes, engage or abort.',
+  '   The plugin asks for its own one-shot approval on engage/protocol run in the real',
+  '   backend; that approval does not replace the user conversation requirement.',
+  '3. Prefer a fixed protocol (labs_protocol) for stable calibration flows. Use labs_set',
+  '   and labs_engage only for exploratory measurements.',
+  '',
+  '## Running',
+  '- labs_set writes the panel. It does not run anything. Always pass note: one sentence',
+  '  saying what this batch is for (it is written to the event log).',
+  '- labs_engage submits a run and returns immediately with n_shots_at_submit and',
+  '  expected_n_shots. Do not poll in a loop; when the user wants results, call labs_wait.',
+  '  After submitting you may end the turn or do independent work.',
+  '- labs_protocol run submits a fixed protocol; labs_wait finalizes it (postprocess,',
+  '  finish write-back, panel restore).',
+  '- backend defaults to mock-labscript; real hardware is only used when the config says',
+  '  backend: labscript explicitly.',
+  '- On a new install or when a tool fails with a configuration error, run labs_doctor first.',
+  '- labs_abort stops compiling/submitting new shots; shots already queued in BLACS or',
+  '  running are not stopped. It is not a hardware interlock. Never call it unless',
+  '  something looks wrong or the user asks.',
+  '- A panel snapshot is taken before every write. labs_restore restores only the keys that',
+  '  write touched (pass full=true for the whole panel), so concurrent edits elsewhere are kept.',
+  '',
+  '## Reading results',
+  '- labs_data reads the run folder HDF5: globals of the first shot and, with scan: a',
+  '  per-shot table. HDF5 is authoritative; the panel is only intermediate state.',
+  '- Report facts: run folder, expected vs actual shots, postprocess numbers, warnings.',
+  '  If a number is missing, say so instead of inventing one.',
+  '',
+  '## Stop rules',
+  '- error_in_globals true: fix or ask; never engage.',
+  '- wait timed out or diagnosis=compiled_not_executed: the shots may be compiled but BLACS',
+  '  may be paused/not executing. Check BLACS and the panel, then abort or ask; do not resubmit blindly.',
+  '- A run is already pending: wait or abort before submitting another.',
+].join(String.fromCharCode(10))
+
+export function registerSkill(ctx) {
+  ctx.skills.register({
+    name: 'labscript',
+    description: 'Control a labscript-suite experiment through the labs_* tools: read the runmanager panel, write globals and scans, submit runs without blocking, wait for completion, run YAML fixed-operation protocols with postprocess write-back, read run HDF5 data, restore panel snapshots.',
+    whenToUse: 'When the user asks to inspect or change the labscript panel, run shots or scans, run a fixed experiment protocol, or read results of a labscript run.',
+    source: 'runtime',
+    content: SKILL_CONTENT,
+    invocation: { modelInvocable: true, userInvocable: true },
+  })
+}

package/lib/store.mjs

@@ -1,136 +1,136 @@
-/**
- * dsh-labscript local state: UI config + runtime pending state.
- *
- * The browser configuration page stores a small JSON file under DSH_HOME. It is
- * merged over the profile config (UI values win for the keys it manages); the
- * other profile keys (scripts, hard limits, postprocess, approval, ...) stay in
- * the profile's cordis.patch.yml. No credentials are stored here.
- */
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-
-export function dshHome() {
-  const fromEnv = process.env.DSH_HOME
-  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return fromEnv
-  return path.join(os.homedir(), '.dsh')
-}
-
-export function uiConfigPath(home) {
-  return path.join(home || dshHome(), 'labscript.config.json')
-}
-
-export function statePath(home) {
-  return path.join(home || dshHome(), 'labscript-state.json')
-}
-
-const UI_KEYS = ['backend', 'python', 'runmanager', 'protocolsDir']
-const BACKENDS = ['labscript', 'mock-labscript', 'http-sim']
-
-export function normalizeUiConfig(input) {
-  const source = input && typeof input === 'object' ? input : {}
-  const backend = String(source.backend || 'mock-labscript').toLowerCase()
-  if (!BACKENDS.includes(backend)) {
-    throw new Error('backend must be one of ' + BACKENDS.join(', ') + ', got: ' + backend)
-  }
-  const runmanager = source.runmanager && typeof source.runmanager === 'object' ? source.runmanager : {}
-  const port = Number(runmanager.port || 42523)
-  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('runmanager.port must be 1-65535')
-  const timeoutS = runmanager.timeoutS === undefined || runmanager.timeoutS === null || runmanager.timeoutS === ''
-    ? undefined
-    : Number(runmanager.timeoutS)
-  if (timeoutS !== undefined && (!Number.isFinite(timeoutS) || timeoutS <= 0 || timeoutS > 600)) {
-    throw new Error('runmanager.timeoutS must be 1-600')
-  }
-  const out = {
-    backend,
-    python: String(source.python || '').trim(),
-    runmanager: {
-      host: String(runmanager.host || '127.0.0.1').trim(),
-      port,
-    },
-    protocolsDir: String(source.protocolsDir || '').trim(),
-  }
-  if (timeoutS !== undefined) out.runmanager.timeoutS = timeoutS
-  return out
-}
-
-/** Read the UI config. Returns null when the file does not exist. */
-export function readUiConfig(home) {
-  const file = uiConfigPath(home)
-  let raw
-  try {
-    raw = fs.readFileSync(file, 'utf8')
-  } catch (error) {
-    if (error && error.code === 'ENOENT') return { config: null, warning: undefined, file }
-    return { config: null, warning: 'cannot read ' + file + ': ' + error.message, file }
-  }
-  try {
-    return { config: normalizeUiConfig(JSON.parse(raw)), warning: undefined, file }
-  } catch (error) {
-    return { config: null, warning: 'ignoring corrupt ' + file + ': ' + error.message, file }
-  }
-}
-
-export function writeUiConfig(input, home) {
-  const previous = readUiConfig(home).config || {}
-  const patch = input && typeof input === 'object' ? input : {}
-  const config = normalizeUiConfig(Object.assign({}, previous, patch, {
-    runmanager: Object.assign({}, previous.runmanager || {}, patch.runmanager || {}),
-  }))
-  const file = uiConfigPath(home)
-  fs.mkdirSync(path.dirname(file), { recursive: true })
-  const temp = file + '.' + process.pid + '.' + Date.now() + '.tmp'
-  try {
-    fs.writeFileSync(temp, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
-    fs.renameSync(temp, file)
-  } finally {
-    try { if (fs.existsSync(temp)) fs.unlinkSync(temp) } catch { /* best effort */ }
-  }
-  return config
-}
-
-/** Merge the UI-managed keys over the profile config (UI wins where present). */
-export function mergeConfig(profile, ui) {
-  const base = profile && typeof profile === 'object' ? profile : {}
-  if (!ui || typeof ui !== 'object') return base
-  const out = Object.assign({}, base)
-  for (const key of UI_KEYS) {
-    if (ui[key] === undefined) continue
-    if (key === 'runmanager') out.runmanager = Object.assign({}, base.runmanager || {}, ui.runmanager || {})
-    else out[key] = ui[key]
-  }
-  return out
-}
-
-export function readState(home) {
-  const file = statePath(home)
-  try {
-    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
-    return {
-      pending: parsed && typeof parsed.pending === 'object' ? parsed.pending : null,
-      lastRun: parsed && typeof parsed.lastRun === 'object' ? parsed.lastRun : null,
-    }
-  } catch {
-    return { pending: null, lastRun: null }
-  }
-}
-
-export function writeState(state, version, home) {
-  const file = statePath(home)
-  fs.mkdirSync(path.dirname(file), { recursive: true })
-  const temp = file + '.' + process.pid + '.' + Date.now() + '.tmp'
-  const payload = {
-    version: version || null,
-    updated_at: new Date().toISOString(),
-    pending: state.pending || null,
-    lastRun: state.lastRun || null,
-  }
-  try {
-    fs.writeFileSync(temp, JSON.stringify(payload, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
-    fs.renameSync(temp, file)
-  } finally {
-    try { if (fs.existsSync(temp)) fs.unlinkSync(temp) } catch { /* best effort */ }
-  }
-  return payload
-}
+/**
+ * dsh-labscript local state: UI config + runtime pending state.
+ *
+ * The browser configuration page stores a small JSON file under DSH_HOME. It is
+ * merged over the profile config (UI values win for the keys it manages); the
+ * other profile keys (scripts, hard limits, postprocess, approval, ...) stay in
+ * the profile's cordis.patch.yml. No credentials are stored here.
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export function dshHome() {
+  const fromEnv = process.env.DSH_HOME
+  if (typeof fromEnv === 'string' && fromEnv.trim() !== '') return fromEnv
+  return path.join(os.homedir(), '.dsh')
+}
+
+export function uiConfigPath(home) {
+  return path.join(home || dshHome(), 'labscript.config.json')
+}
+
+export function statePath(home) {
+  return path.join(home || dshHome(), 'labscript-state.json')
+}
+
+const UI_KEYS = ['backend', 'python', 'runmanager', 'protocolsDir']
+const BACKENDS = ['labscript', 'mock-labscript', 'http-sim']
+
+export function normalizeUiConfig(input) {
+  const source = input && typeof input === 'object' ? input : {}
+  const backend = String(source.backend || 'mock-labscript').toLowerCase()
+  if (!BACKENDS.includes(backend)) {
+    throw new Error('backend must be one of ' + BACKENDS.join(', ') + ', got: ' + backend)
+  }
+  const runmanager = source.runmanager && typeof source.runmanager === 'object' ? source.runmanager : {}
+  const port = Number(runmanager.port || 42523)
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('runmanager.port must be 1-65535')
+  const timeoutS = runmanager.timeoutS === undefined || runmanager.timeoutS === null || runmanager.timeoutS === ''
+    ? undefined
+    : Number(runmanager.timeoutS)
+  if (timeoutS !== undefined && (!Number.isFinite(timeoutS) || timeoutS <= 0 || timeoutS > 600)) {
+    throw new Error('runmanager.timeoutS must be 1-600')
+  }
+  const out = {
+    backend,
+    python: String(source.python || '').trim(),
+    runmanager: {
+      host: String(runmanager.host || '127.0.0.1').trim(),
+      port,
+    },
+    protocolsDir: String(source.protocolsDir || '').trim(),
+  }
+  if (timeoutS !== undefined) out.runmanager.timeoutS = timeoutS
+  return out
+}
+
+/** Read the UI config. Returns null when the file does not exist. */
+export function readUiConfig(home) {
+  const file = uiConfigPath(home)
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return { config: null, warning: undefined, file }
+    return { config: null, warning: 'cannot read ' + file + ': ' + error.message, file }
+  }
+  try {
+    return { config: normalizeUiConfig(JSON.parse(raw)), warning: undefined, file }
+  } catch (error) {
+    return { config: null, warning: 'ignoring corrupt ' + file + ': ' + error.message, file }
+  }
+}
+
+export function writeUiConfig(input, home) {
+  const previous = readUiConfig(home).config || {}
+  const patch = input && typeof input === 'object' ? input : {}
+  const config = normalizeUiConfig(Object.assign({}, previous, patch, {
+    runmanager: Object.assign({}, previous.runmanager || {}, patch.runmanager || {}),
+  }))
+  const file = uiConfigPath(home)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const temp = file + '.' + process.pid + '.' + Date.now() + '.tmp'
+  try {
+    fs.writeFileSync(temp, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
+    fs.renameSync(temp, file)
+  } finally {
+    try { if (fs.existsSync(temp)) fs.unlinkSync(temp) } catch { /* best effort */ }
+  }
+  return config
+}
+
+/** Merge the UI-managed keys over the profile config (UI wins where present). */
+export function mergeConfig(profile, ui) {
+  const base = profile && typeof profile === 'object' ? profile : {}
+  if (!ui || typeof ui !== 'object') return base
+  const out = Object.assign({}, base)
+  for (const key of UI_KEYS) {
+    if (ui[key] === undefined) continue
+    if (key === 'runmanager') out.runmanager = Object.assign({}, base.runmanager || {}, ui.runmanager || {})
+    else out[key] = ui[key]
+  }
+  return out
+}
+
+export function readState(home) {
+  const file = statePath(home)
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return {
+      pending: parsed && typeof parsed.pending === 'object' ? parsed.pending : null,
+      lastRun: parsed && typeof parsed.lastRun === 'object' ? parsed.lastRun : null,
+    }
+  } catch {
+    return { pending: null, lastRun: null }
+  }
+}
+
+export function writeState(state, version, home) {
+  const file = statePath(home)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const temp = file + '.' + process.pid + '.' + Date.now() + '.tmp'
+  const payload = {
+    version: version || null,
+    updated_at: new Date().toISOString(),
+    pending: state.pending || null,
+    lastRun: state.lastRun || null,
+  }
+  try {
+    fs.writeFileSync(temp, JSON.stringify(payload, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
+    fs.renameSync(temp, file)
+  } finally {
+    try { if (fs.existsSync(temp)) fs.unlinkSync(temp) } catch { /* best effort */ }
+  }
+  return payload
+}