dsh-labscript 0.0.0-stage → 0.2.1

package/lib/index.js

@@ -0,0 +1,138 @@
+/**
+ * dsh-labscript -- host half.
+ *
+ * Registers the labs_* tools, the runtime skill, and a small HTTP API used by
+ * the browser configuration page. The browser half is optional: the tools work
+ * without it, and the page only edits the four connection settings (backend,
+ * python, runmanager host/port, protocolsDir).
+ */
+import fs from 'node:fs'
+import { createRuntime, LabError } from './runtime.js'
+import { registerTools } from './tools.js'
+import { registerSkill } from './skill.js'
+import { writeUiConfig } from './store.mjs'
+
+export const name = 'dsh-labscript'
+export const inject = ['tools', 'skills']
+
+const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+const API_PREFIX = '/dsh-labscript/api'
+const MAX_BODY_BYTES = 64 * 1024
+
+function sendJson(response, status, body) {
+  response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' })
+  response.end(JSON.stringify(body))
+}
+
+function readJsonBody(request) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    request.on('data', (chunk) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error('request body too large'))
+        request.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    request.on('end', () => {
+      try {
+        resolve(chunks.length === 0 ? {} : JSON.parse(Buffer.concat(chunks).toString('utf8')))
+      } catch (error) {
+        reject(new Error('request body is not JSON'))
+      }
+    })
+    request.on('error', reject)
+  })
+}
+
+function isTrustedRequest(ctx, request) {
+  let connection
+  try {
+    connection = typeof ctx.get === 'function' ? ctx.get('connection') : undefined
+  } catch {
+    connection = undefined
+  }
+  if (connection === undefined) return false
+  try {
+    if (typeof connection.isTrusted === 'function' && connection.isTrusted(request) === true) return true
+    if (typeof connection.requestRejection === 'function') {
+      const code = connection.requestRejection(request)
+      return code === undefined || code === null || code === false
+    }
+  } catch {
+    /* fall through to reject */
+  }
+  return false
+}
+
+function registerRoutes(ctx, runtime) {
+  const webServer = typeof ctx.get === 'function' ? ctx.get('webServer') : ctx.webServer
+  if (!webServer || typeof webServer.register !== 'function') return
+  const handler = async (request, response) => {
+    const url = new URL(request.url || '/', 'http://127.0.0.1')
+    if (!url.pathname.startsWith(API_PREFIX)) {
+      sendJson(response, 404, { ok: false, error: 'not found' })
+      return
+    }
+    if (!isTrustedRequest(ctx, request)) {
+      sendJson(response, 403, { ok: false, error: 'untrusted request origin' })
+      return
+    }
+    const route = url.pathname.slice(API_PREFIX.length).replace(/\/+$/, '') || '/'
+    try {
+      if (route === '/config' && request.method === 'GET') {
+        const config = runtime.config
+        const doctorInfo = { configFile: runtime.uiConfigPath(), stateFile: runtime.statePath(), python: config.python }
+        sendJson(response, 200, {
+          ok: true,
+          version: runtime.version,
+          packageName: PACKAGE.name,
+          ...doctorInfo,
+          config: {
+            backend: config.backend,
+            python: config.python,
+            runmanager: config.runmanager,
+            protocolsDir: config.protocolsDir,
+          },
+        })
+        return
+      }
+      if (route === '/config' && request.method === 'POST') {
+        const body = await readJsonBody(request)
+        const stored = writeUiConfig(body, runtime.uiHome)
+        sendJson(response, 200, { ok: true, config: stored })
+        return
+      }
+      if (route === '/doctor' && request.method === 'POST') {
+        const result = await runtime.doctor()
+        sendJson(response, 200, { ok: true, ...result })
+        return
+      }
+      sendJson(response, 404, { ok: false, error: 'not found' })
+    } catch (error) {
+      sendJson(response, 400, { ok: false, error: error && error.message ? error.message : String(error) })
+    }
+  }
+  ctx.effect(() => webServer.register({ kind: 'prefix', path: API_PREFIX, handler }))
+}
+
+export function apply(ctx, config) {
+  const runtime = createRuntime(ctx, config)
+  registerTools(ctx, runtime)
+  registerSkill(ctx)
+  registerRoutes(ctx, runtime)
+  const logger = ctx.logger
+  if (logger && typeof logger.info === 'function') {
+    const current = runtime.config
+    logger.info('[dsh-labscript] v' + runtime.version + ' backend=' + current.backend + ' python=' + (current.python || '<unset>'))
+    if (current.backend === 'labscript' && !current.python) {
+      logger.warn('[dsh-labscript] backend is labscript but config.python is empty; every hardware tool will fail')
+    }
+  }
+  return runtime
+}
+
+export { LabError }

package/lib/protocols.js

@@ -0,0 +1,112 @@
+/**
+ * Protocol files: discovery, YAML parsing, name resolution.
+ *
+ * A protocol is a YAML mapping. The schema is deliberately small: name,
+ * labscript (or joint_script), set, scan, reps, engage, postprocess,
+ * finish.restore/panel/history. Unknown keys are reported as warnings; the
+ * legacy key "analysis" is accepted as an alias for "postprocess".
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import YAML from 'yaml'
+
+const KNOWN_KEYS = new Set(['name', 'labscript', 'joint_script', 'set', 'scan', 'reps', 'engage', 'postprocess', 'finish', 'analysis'])
+const MAX_PROTOCOL_BYTES = 256 * 1024
+
+function protocolFiles(dir) {
+  if (!dir) return []
+  let entries = []
+  try {
+    entries = fs.readdirSync(dir)
+  } catch (error) {
+    return []
+  }
+  return entries
+    .filter((name) => name.endsWith('.yaml') || name.endsWith('.yml'))
+    .sort()
+    .map((name) => path.join(dir, name))
+}
+
+export function listProtocols(dir) {
+  return protocolFiles(dir).map((file) => {
+    try {
+      const loaded = loadProtocolFile(file)
+      return { name: loaded.name, file: path.basename(file), warnings: loaded.warnings }
+    } catch (error) {
+      return { name: path.basename(file), file: path.basename(file), error: error.message }
+    }
+  })
+}
+
+export function resolveProtocolPath(dir, ref) {
+  const value = String(ref || '').trim()
+  if (!value) throw new Error('protocol name is required')
+  if (path.isAbsolute(value)) {
+    if (fs.existsSync(value)) return value
+    throw new Error('protocol file not found: ' + value)
+  }
+  const candidates = [path.join(dir || '', value)]
+  if (!value.endsWith('.yaml') && !value.endsWith('.yml')) {
+    candidates.push(path.join(dir || '', value + '.yaml'))
+    candidates.push(path.join(dir || '', value + '.yml'))
+  }
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate
+  }
+  throw new Error('protocol not found in protocolsDir: ' + value)
+}
+
+export function loadProtocol(dir, ref) {
+  return loadProtocolFile(resolveProtocolPath(dir, ref))
+}
+
+export function loadProtocolFile(file) {
+  const stat = fs.statSync(file)
+  if (stat.size > MAX_PROTOCOL_BYTES) throw new Error('protocol file is too large: ' + file)
+  const text = fs.readFileSync(file, 'utf8')
+  let data
+  try {
+    data = YAML.parse(text)
+  } catch (error) {
+    throw new Error('cannot parse protocol YAML ' + path.basename(file) + ': ' + error.message)
+  }
+  return normalizeProtocol(data, file)
+}
+
+export function normalizeProtocol(data, file) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw new Error('protocol must be a YAML mapping: ' + (file || 'inline'))
+  }
+  const warnings = []
+  for (const key of Object.keys(data)) {
+    if (!KNOWN_KEYS.has(key)) warnings.push('unknown protocol key ignored: ' + key)
+  }
+  const plan = {
+    name: data.name ? String(data.name) : path.basename(file || 'protocol').replace(/\.ya?ml$/, ''),
+    labscript: data.labscript ? String(data.labscript) : undefined,
+    joint_script: data.joint_script ? String(data.joint_script) : undefined,
+    set: data.set && typeof data.set === 'object' ? Object.assign({}, data.set) : {},
+    scan: data.scan && typeof data.scan === 'object' ? Object.assign({}, data.scan) : {},
+    reps: data.reps === undefined ? 1 : data.reps,
+    engage: data.engage === undefined ? true : Boolean(data.engage),
+    postprocess: null,
+    finish: { restore: true, panel: {}, history: {} },
+  }
+  if (data.analysis !== undefined && data.postprocess === undefined) {
+    plan.postprocess = data.analysis ? String(data.analysis) : null
+    warnings.push('legacy key "analysis" used as "postprocess"')
+  } else if (data.postprocess !== undefined) {
+    plan.postprocess = data.postprocess ? String(data.postprocess) : null
+  }
+  if (data.finish && typeof data.finish === 'object') {
+    plan.finish.restore = data.finish.restore === undefined ? true : Boolean(data.finish.restore)
+    if (data.finish.panel && typeof data.finish.panel === 'object') plan.finish.panel = Object.assign({}, data.finish.panel)
+    if (data.finish.history && typeof data.finish.history === 'object') plan.finish.history = Object.assign({}, data.finish.history)
+    for (const key of Object.keys(data.finish)) {
+      if (!['restore', 'panel', 'history'].includes(key)) warnings.push('unknown finish key ignored: ' + key)
+    }
+  }
+  if (!plan.labscript && !plan.joint_script) throw new Error('protocol needs "labscript" or "joint_script": ' + (file || 'inline'))
+  if (!Number.isInteger(plan.reps) || plan.reps < 1) throw new Error('protocol reps must be a positive integer: ' + (file || 'inline'))
+  return { name: plan.name, file: file || null, plan, warnings }
+}

package/lib/runtime.js

@@ -0,0 +1,350 @@
+/**
+ * dsh-labscript runtime: effective configuration, python bridge transport and
+ * runtime state.
+ *
+ * Every tool call spawns the bundled python bridge once, writes one JSON
+ * request on stdin and reads one JSON envelope from stdout. The bridge is a
+ * short-lived process: timeouts and cancellation kill it.
+ *
+ * Configuration comes from two places and is merged on every read: the profile
+ * config (advanced settings) and the small JSON file written by the browser
+ * configuration page (backend, python, runmanager, protocolsDir). Pending-run
+ * state is persisted under DSH_HOME so a restart does not lose track of a run.
+ */
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  mergeConfig,
+  readState,
+  readUiConfig,
+  statePath,
+  uiConfigPath,
+  writeState,
+} from './store.mjs'
+
+const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+const VERSION = PACKAGE.version
+const DEFAULT_ENGAGE_TIMEOUT_S = 900
+const DEFAULT_APPROVAL = { engage: true, protocolRun: true, protocolNames: true }
+const DEFAULT_BACKEND = 'mock-labscript'
+const BACKENDS = ['labscript', 'mock-labscript', 'http-sim']
+
+export class LabError extends Error {
+  constructor(code, message, detail) {
+    super(message)
+    this.name = 'LabError'
+    this.code = code
+    this.detail = detail || null
+  }
+}
+
+function normalizeConfig(raw) {
+  const input = raw && typeof raw === 'object' ? raw : {}
+  const backend = String(input.backend || DEFAULT_BACKEND).toLowerCase()
+  if (!BACKENDS.includes(backend)) {
+    throw new LabError('BAD_CONFIG', 'backend must be "labscript", "mock-labscript" or "http-sim", got: ' + backend)
+  }
+  const approval = Object.assign({}, DEFAULT_APPROVAL, input.approval || {})
+  return {
+    python: input.python || '',
+    bridgeScript: input.bridgeScript || '',
+    backend,
+    runmanager: input.runmanager || {},
+    protocolsDir: input.protocolsDir || '',
+    scriptsFile: input.scriptsFile || '',
+    hardLimitsFile: input.hardLimitsFile || '',
+    calibrationLog: input.calibrationLog || '',
+    pathMap: input.pathMap || [],
+    reps: input.reps || {},
+    postprocess: input.postprocess || {},
+    engage: input.engage || {},
+    panelHistoryDir: input.panelHistoryDir || '',
+    approval: {
+      engage: approval.engage !== false,
+      protocolRun: approval.protocolRun !== false,
+      protocolNames: approval.protocolNames !== false,
+    },
+    mock: input.mock || {},
+    simulator: input.simulator || {},
+    dshHome: input.dshHome || '',
+    requestTimeoutMs: Number(input.requestTimeoutMs || 60000),
+  }
+}
+
+function bridgePayload(config) {
+  return {
+    backend: config.backend,
+    runmanager: config.runmanager,
+    scriptsFile: config.scriptsFile,
+    hardLimitsFile: config.hardLimitsFile,
+    calibrationLog: config.calibrationLog,
+    pathMap: config.pathMap,
+    reps: config.reps,
+    postprocess: config.postprocess,
+    engage: Object.assign({ timeoutS: DEFAULT_ENGAGE_TIMEOUT_S }, config.engage || {}),
+    panelHistoryDir: config.panelHistoryDir,
+    mock: config.mock,
+    simulator: config.simulator,
+  }
+}
+
+export function createRuntime(ctx, rawConfig) {
+  const profileConfig = rawConfig && typeof rawConfig === 'object' ? rawConfig : {}
+  const home = typeof profileConfig.dshHome === 'string' && profileConfig.dshHome !== '' ? profileConfig.dshHome : undefined
+  let uiCache = { key: 'unread', config: null, warning: undefined, file: uiConfigPath(home) }
+
+  function uiState() {
+    const file = uiConfigPath(home)
+    let stat
+    try {
+      stat = fs.statSync(file)
+    } catch {
+      uiCache = { key: 'missing', config: null, warning: undefined, file }
+      return uiCache
+    }
+    const key = String(stat.mtimeMs) + ':' + stat.size
+    if (key !== uiCache.key) {
+      const read = readUiConfig(home)
+      uiCache = { key, config: read.config, warning: read.warning, file }
+    }
+    return uiCache
+  }
+
+  function currentConfig() {
+    return normalizeConfig(mergeConfig(profileConfig, uiState().config))
+  }
+
+  // Fail fast on a broken profile config instead of failing on the first tool call.
+  currentConfig()
+
+  const loadedState = readState(home)
+  const state = {
+    pending: loadedState.pending,
+    lastRun: loadedState.lastRun,
+    queue: Promise.resolve(),
+    active: {},
+    waitCancelledByAbort: false,
+  }
+
+  function saveState() {
+    try {
+      writeState(state, VERSION, home)
+    } catch {
+      /* state persistence is best effort */
+    }
+  }
+
+  function setPending(pending) {
+    state.pending = pending || null
+    saveState()
+  }
+
+  function setLastRun(lastRun) {
+    state.lastRun = lastRun || null
+    saveState()
+  }
+
+  function clearPending() {
+    state.pending = null
+    saveState()
+  }
+
+  function runBridge(command, args, options) {
+    const opts = options || {}
+    let config
+    try {
+      config = currentConfig()
+    } catch (error) {
+      return Promise.reject(error)
+    }
+    if (!config.python) {
+      return Promise.reject(new LabError('BAD_CONFIG', 'config.python is required (path to a python interpreter with numpy and h5py; use the labscript-suite environment for real hardware)'))
+    }
+    return new Promise((resolve, reject) => {
+      let settled = false
+      let child
+      const finish = (error, value) => {
+        if (settled) return
+        settled = true
+        if (error) reject(error)
+        else resolve(value)
+      }
+      try {
+        child = spawn(config.python, [bridgeScriptOf(config)], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
+        state.active[command] = child
+      } catch (error) {
+        finish(new LabError('SPAWN_FAILED', 'cannot spawn python bridge: ' + error.message))
+        return
+      }
+      const stdout = []
+      const stderr = []
+      const timeoutMs = Number(opts.timeoutMs || config.requestTimeoutMs)
+      const timer = setTimeout(() => {
+        try { child.kill() } catch { /* ignore */ }
+        finish(new LabError('TIMEOUT', 'bridge call timed out after ' + timeoutMs + ' ms: ' + command, {
+          hint: command === 'wait' ? 'the run may still be executing; use labs_wait with run_folder or labs_abort' : undefined,
+        }))
+      }, timeoutMs)
+      const onAbort = () => {
+        try { child.kill() } catch { /* ignore */ }
+        finish(new LabError('ABORTED', 'bridge call cancelled: ' + command, {
+          hint: command === 'wait' ? 'the run may still be executing; use labs_wait with run_folder or labs_abort' : undefined,
+        }))
+      }
+      if (opts.signal) {
+        if (opts.signal.aborted) onAbort()
+        else opts.signal.addEventListener('abort', onAbort, { once: true })
+      }
+      child.stdout.on('data', (chunk) => stdout.push(chunk))
+      child.stderr.on('data', (chunk) => stderr.push(chunk))
+      child.on('error', (error) => {
+        if (state.active[command] === child) delete state.active[command]
+        clearTimeout(timer)
+        if (opts.signal) opts.signal.removeEventListener('abort', onAbort)
+        finish(new LabError('SPAWN_FAILED', 'python bridge failed: ' + error.message))
+      })
+      child.on('close', (code) => {
+        if (state.active[command] === child) delete state.active[command]
+        clearTimeout(timer)
+        if (opts.signal) opts.signal.removeEventListener('abort', onAbort)
+        const cancelledByAbort = command === 'wait' && state.waitCancelledByAbort
+        const outText = Buffer.concat(stdout).toString('utf8').trim()
+        const errText = Buffer.concat(stderr).toString('utf8').trim()
+        if (!outText) {
+          if (cancelledByAbort) {
+            finish(new LabError('ABORTED', 'wait cancelled by labs_abort'))
+            return
+          }
+          finish(new LabError('BRIDGE_EMPTY_OUTPUT', 'bridge produced no JSON (exit ' + code + '): ' + tail(errText)))
+          return
+        }
+        let envelope
+        try {
+          envelope = JSON.parse(outText)
+        } catch {
+          finish(new LabError('BRIDGE_BAD_JSON', 'bridge output is not JSON: ' + tail(outText)))
+          return
+        }
+        if (!envelope || envelope.ok !== true) {
+          const info = envelope && envelope.error ? envelope.error : {}
+          finish(new LabError(info.code || 'BRIDGE_ERROR', info.message || 'bridge error', info.detail || null))
+          return
+        }
+        finish(null, envelope.data)
+      })
+      try {
+        child.stdin.write(JSON.stringify({ cmd: command, args: args || {}, config: bridgePayload(config) }))
+        child.stdin.end()
+      } catch (error) {
+        try { child.kill() } catch { /* ignore */ }
+        finish(new LabError('SPAWN_FAILED', 'cannot write to python bridge: ' + error.message))
+      }
+    })
+  }
+
+  function bridgeScriptOf(config) {
+    return config.bridgeScript || fileURLToPath(new URL('../python/bridge.py', import.meta.url))
+  }
+
+  function cancelWait() {
+    const child = state.active.wait
+    if (!child) return false
+    state.waitCancelledByAbort = true
+    try {
+      child.kill()
+    } catch {
+      /* ignore */
+    }
+    return true
+  }
+
+  function serial(task) {
+    const run = state.queue.then(task, task)
+    state.queue = run.then(() => undefined, () => undefined)
+    return run
+  }
+
+  async function doctor() {
+    const checks = []
+    const add = (name, status, detail, hint) => checks.push({ name, status, detail: detail || '', hint: hint || '' })
+    let config
+    try {
+      config = currentConfig()
+      add('config', 'ok', 'profile config loaded')
+    } catch (error) {
+      add('config', 'fail', error.message, 'fix the profile cordis.patch.yml config')
+      return { version: VERSION, backend: 'unknown', checks, configFile: uiState().file, stateFile: statePath(home) }
+    }
+    add('version', 'ok', 'dsh-labscript ' + VERSION)
+    add('backend', config.backend === 'labscript' ? 'warn' : 'ok', config.backend, config.backend === 'labscript' ? 'REAL HARDWARE mode: engage writes to the live panel' : 'simulator mode')
+    const pythonSet = config.python !== ''
+    const pythonIsFile = pythonSet && fs.existsSync(config.python)
+    const pythonHasSeparator = pythonSet && (config.python.includes('/') || config.python.includes('\\'))
+    const pythonStatus = !pythonSet ? 'fail' : pythonIsFile ? 'ok' : pythonHasSeparator ? 'fail' : 'warn'
+    add('python-path', pythonStatus, config.python || '(not configured)',
+      !pythonSet ? 'set the labscript-suite python interpreter (or any python with numpy+h5py for mock)'
+        : pythonStatus === 'fail' ? 'path does not exist'
+        : pythonStatus === 'warn' ? 'not an absolute file path; will be resolved through PATH'
+        : '')
+    let approval = null
+    try { approval = typeof ctx.get === 'function' ? ctx.get('approval') : undefined } catch { approval = undefined }
+    add('approval', approval ? 'ok' : 'warn', approval ? 'approval service available' : 'no approval service', approval ? '' : 'real-hardware engage/protocol run will be refused')
+    try {
+      fs.mkdirSync(path.dirname(statePath(home)), { recursive: true })
+      fs.accessSync(path.dirname(statePath(home)), fs.constants.W_OK)
+      add('state-dir', 'ok', path.dirname(statePath(home)))
+    } catch (error) {
+      add('state-dir', 'fail', path.dirname(statePath(home)), 'cannot write runtime state: ' + error.message)
+    }
+    if (config.protocolsDir) {
+      add('protocols-dir', fs.existsSync(config.protocolsDir) ? 'ok' : 'warn', config.protocolsDir, fs.existsSync(config.protocolsDir) ? '' : 'directory does not exist (lists will be empty)')
+    }
+    if (config.python) {
+      try {
+        const data = await runBridge('doctor', {}, { timeoutMs: 60000 })
+        for (const check of data.checks || []) checks.push(check)
+      } catch (error) {
+        add('python-bridge', 'fail', error.message, error.detail && error.detail.hint ? error.detail.hint : 'run the bridge manually to see the traceback')
+      }
+    }
+    return {
+      version: VERSION,
+      backend: config.backend,
+      checks,
+      configFile: uiState().file,
+      stateFile: statePath(home),
+      python: config.python,
+    }
+  }
+
+  return {
+    ctx,
+    version: VERSION,
+    uiHome: home,
+    statePath: () => statePath(home),
+    uiConfigPath: () => uiConfigPath(home),
+    get config() {
+      return currentConfig()
+    },
+    state,
+    setPending,
+    setLastRun,
+    clearPending,
+    saveState,
+    cancelWait,
+    runBridge,
+    serial,
+    doctor,
+    isMock() {
+      return currentConfig().backend === 'mock-labscript'
+    },
+  }
+}
+
+function tail(text) {
+  if (!text) return ''
+  const lines = text.split(String.fromCharCode(10))
+  return lines.slice(-8).join('; ')
+}

package/lib/skill.js

@@ -0,0 +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 },
+  })
+}