@lincyaw/addon-exec 0.0.0-stage → 1.0.0-rc.1

package/src/client/script/executor.ts

@@ -0,0 +1,62 @@
+import { siteBase } from '@lincyaw/host'
+import { failedRun } from '@lincyaw/kernel'
+import type { Executor, RunResult } from '@lincyaw/kernel'
+import { isScript, isTypeScript, SCRIPT_IMPORTS } from '../../domain/index.ts'
+import type { ScriptOutput, ScriptRequest } from '../../shared/script-runner.mjs'
+import { messages } from '../messages.ts'
+
+export const BROWSER_SCRIPT_EXECUTOR_ID = 'js-worker'
+
+export type ScriptExecutor = Executor & { dispose(): void }
+
+function imports(): Record<string, string> {
+  return Object.fromEntries(Object.entries(SCRIPT_IMPORTS).map(([name, path]) => [name, new URL(`${siteBase()}${path}`, location.href).href]))
+}
+
+export function createScriptExecutor(options: { timeoutMs: number }): ScriptExecutor {
+  const id = BROWSER_SCRIPT_EXECUTOR_ID
+  const active = new Set<() => void>()
+  let disposed = false
+  return {
+    id,
+    runsIn: 'browser',
+    supports: isScript,
+    run(request, signal) {
+      return new Promise<RunResult>((resolve) => {
+        if (disposed || signal?.aborted) return resolve(failedRun(id, messages().cancelled))
+        const worker = new Worker(new URL('./script.worker.ts', import.meta.url), { type: 'module', name: 'presmium-js' })
+        const started = performance.now()
+        const elapsed = () => Math.round(performance.now() - started)
+        const timeoutMs = request.timeoutMs ?? options.timeoutMs
+        let finished = false
+        const finish = (result: RunResult) => {
+          if (finished) return
+          finished = true
+          active.delete(onAbort)
+          clearTimeout(timer)
+          worker.onmessage = null
+          worker.onerror = null
+          worker.terminate()
+          signal?.removeEventListener('abort', onAbort)
+          resolve(result)
+        }
+        const onAbort = () => finish(failedRun(id, messages().cancelled, elapsed()))
+        const timer = setTimeout(() => finish({ ...failedRun(id, messages().runTimeout(timeoutMs), elapsed()), timedOut: true }), timeoutMs)
+        active.add(onAbort)
+        worker.onmessage = ({ data }: MessageEvent<ScriptOutput>) => finish({
+          ok: data.exitCode === 0, ...data, durationMs: elapsed(), timedOut: false, source: 'live', executorId: id,
+        })
+        worker.onerror = event => finish(failedRun(id, messages().runtimeCrashed('JavaScript', event.message), elapsed()))
+        signal?.addEventListener('abort', onAbort)
+        const message: ScriptRequest = { code: request.code, args: { ...request.args }, typescript: isTypeScript(request.lang), imports: imports() }
+        worker.postMessage(message)
+      })
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      for (const cancel of [...active]) cancel()
+      active.clear()
+    },
+  }
+}

package/src/client/script/script.worker.ts

@@ -0,0 +1,9 @@
+/// <reference lib="webworker" />
+import { runScript } from '../../shared/script-runner.mjs'
+import type { ScriptRequest } from '../../shared/script-runner.mjs'
+
+declare const self: DedicatedWorkerGlobalScope
+
+self.onmessage = async ({ data }: MessageEvent<ScriptRequest>) => {
+  self.postMessage(await runScript(data))
+}

package/src/client/slide-fit.ts

@@ -0,0 +1,61 @@
+import { useLayoutEffect, useRef } from 'react'
+import type { RefObject } from 'react'
+
+const px = (value: string) => Number.parseFloat(value) || 0
+
+function slideOf(el: HTMLElement): HTMLElement | undefined {
+  const path: HTMLElement[] = []
+  for (let box = el.parentElement; box; box = box.parentElement) {
+    path.push(box)
+    if (getComputedStyle(box).overflowY !== 'hidden') continue
+    const { top, bottom } = box.getBoundingClientRect()
+    return path.find((inner) => {
+      const covers = inner.getBoundingClientRect()
+      return Math.abs(covers.top - top) < 1 && Math.abs(covers.bottom - bottom) < 1
+    })
+  }
+}
+
+function layoutTop(el: HTMLElement): number {
+  let top = el.offsetTop
+  for (let box = el.offsetParent; box instanceof HTMLElement; box = box.offsetParent) top += box.clientTop + box.offsetTop
+  return top
+}
+
+function spaceBelow(el: HTMLElement): number | undefined {
+  const slide = el.offsetParent ? slideOf(el) : undefined
+  if (!slide?.clientHeight) return undefined
+  let below = px(getComputedStyle(el).marginBottom)
+  for (let box = el.parentElement; box && box !== slide; box = box.parentElement) {
+    const style = getComputedStyle(box)
+    below += px(style.paddingBottom) + px(style.borderBottomWidth)
+  }
+  const top = layoutTop(el) - layoutTop(slide) - slide.clientTop
+  return Math.max(0, slide.clientHeight - px(getComputedStyle(slide).paddingBottom) - top - below)
+}
+
+/** Calls `fit` with the height left below the element on its slide, again whenever the layout around it changes. */
+export function useSlideSpaceBelow(el: RefObject<HTMLElement | null | undefined>, active: boolean, fit: (space: number) => void): void {
+  const callback = useRef(fit)
+  callback.current = fit
+  useLayoutEffect(() => {
+    const target = el.current
+    if (!active || !target) return
+    let disposed = false
+    const measure = () => {
+      if (disposed) return
+      const space = spaceBelow(target)
+      if (space !== undefined) callback.current(space)
+    }
+    const observer = new ResizeObserver(measure)
+    observer.observe(target)
+    for (let box = target; box.parentElement; box = box.parentElement) {
+      for (let before = box.previousElementSibling; before; before = before.previousElementSibling) observer.observe(before)
+      observer.observe(box.parentElement)
+      if (getComputedStyle(box.parentElement).overflowY === 'hidden') break
+    }
+    measure()
+    void document.fonts?.ready.then(measure)
+    return () => { disposed = true; observer.disconnect() }
+  }, [el, active])
+}

package/src/client/step-marks.ts

@@ -0,0 +1,7 @@
+import { createContext } from 'react'
+import type { StepState } from '@lincyaw/kernel'
+export function markLine(container: HTMLElement | null | undefined, line: number | undefined, className: string): void {
+  container?.querySelectorAll('code .line').forEach((el, i) => el.classList.toggle(className, i + 1 === line))
+}
+export type RegisterStepMark = (step: number, state: StepState) => () => void
+export const STEP_MARKS = createContext<RegisterStepMark | undefined>(undefined)

package/src/client/when-service.ts

@@ -0,0 +1,14 @@
+import { presmiumReport, presmiumService, runtimeRevision } from '@lincyaw/host'
+import type { ServiceToken } from '@lincyaw/kernel'
+
+export function whenService<T>(token: ServiceToken<T>): Promise<T | undefined> {
+  const initial = presmiumService(token)
+  if (initial || presmiumReport()) return Promise.resolve(initial)
+  return new Promise(resolve => {
+    const stop = runtimeRevision.subscribe(() => {
+      const service = presmiumService(token)
+      if (!service && !presmiumReport()) return
+      stop(); resolve(service)
+    })
+  })
+}

package/src/domain/browser-python.ts

@@ -0,0 +1,33 @@
+const STDLIB = new Set(`abc annotationlib antigravity argparse array ast asyncio atexit base64 bdb binascii bisect builtins bz2
+cProfile calendar cmath cmd code codecs codeop collections colorsys compileall compression concurrent configparser
+contextlib contextvars copy copyreg csv ctypes curses dataclasses datetime dbm decimal difflib dis doctest email
+encodings ensurepip enum errno faulthandler fcntl filecmp fileinput fnmatch fractions ftplib functools gc genericpath
+getopt getpass gettext glob graphlib grp gzip hashlib heapq hmac html http idlelib imaplib importlib inspect io
+ipaddress itertools json keyword linecache locale logging lzma mailbox marshal math mimetypes mmap modulefinder msvcrt
+multiprocessing netrc nt ntpath nturl2path numbers opcode operator optparse os pathlib pdb pickle pickletools pkgutil
+platform plistlib poplib posix posixpath pprint profile pstats pty pwd py_compile pyclbr pydoc pydoc_data pyexpat queue
+quopri random re readline reprlib resource rlcompleter runpy sched secrets select selectors shelve shlex shutil signal
+site smtplib socket socketserver sqlite3 sre_compile sre_constants sre_parse ssl stat statistics string stringprep
+struct subprocess symtable sys sysconfig syslog tabnanny tarfile tempfile termios textwrap this threading time timeit
+tkinter token tokenize tomllib trace traceback tracemalloc tty turtle turtledemo types typing unicodedata unittest
+urllib uuid venv warnings wave weakref webbrowser winreg winsound wsgiref xml xmlrpc zipapp zipfile zipimport zlib
+zoneinfo`.split(/\s+/))
+
+const BROWSER = new Set(['pyodide', 'pyodide_js', 'js', 'IPython', 'presmium_gpu'])
+
+/** Whether Python in the browser (Pyodide, without packages) can import the top-level module. */
+export function importableInBrowser(module: string): boolean {
+  return module.startsWith('_') || STDLIB.has(module) || BROWSER.has(module)
+}
+
+export function pythonImports(code: string): string[] {
+  const names: string[] = []
+  for (const [, from, list] of code.matchAll(/^[ \t]*(?:from[ \t]+([A-Za-z_][\w.]*)[ \t]+import\b|import[ \t]+([^#;\n]+))/gm)) {
+    const modules = from ? [from] : list!.split(',').map(part => part.trim().split(/[ \t]+/)[0]!)
+    for (const module of modules) {
+      const name = module.split('.')[0]!
+      if (/^[A-Za-z_]\w*$/.test(name) && !names.includes(name)) names.push(name)
+    }
+  }
+  return names
+}

package/src/domain/config.ts

@@ -0,0 +1,41 @@
+import { languageId } from '@lincyaw/kernel'
+
+export const EXEC_ID = 'presmium.exec'
+
+export interface ExecConfig {
+  timeoutMs: number
+  loadTimeoutMs: number
+  maxTraceEvents: number
+  pyodideURL?: string
+}
+
+export const DEFAULT_EXEC_CONFIG: ExecConfig = { timeoutMs: 10_000, loadTimeoutMs: 30_000, maxTraceEvents: 500 }
+
+const positive = (value: unknown, fallback: number) => (typeof value === 'number' && value > 0 ? value : fallback)
+
+export function execConfig(raw: Record<string, unknown>): ExecConfig {
+  return {
+    timeoutMs: positive(raw.timeoutMs, DEFAULT_EXEC_CONFIG.timeoutMs),
+    loadTimeoutMs: positive(raw.loadTimeoutMs, DEFAULT_EXEC_CONFIG.loadTimeoutMs),
+    maxTraceEvents: positive(raw.maxTraceEvents, DEFAULT_EXEC_CONFIG.maxTraceEvents),
+    pyodideURL: typeof raw.pyodideURL === 'string' && raw.pyodideURL ? raw.pyodideURL : undefined,
+  }
+}
+
+export function configuredTimeout(raw: Record<string, unknown>): number | undefined {
+  return typeof raw.timeoutMs === 'number' && raw.timeoutMs > 0 ? raw.timeoutMs : undefined
+}
+
+export function isPython(lang: string): boolean {
+  return languageId(lang) === 'python'
+}
+
+export function isScript(lang: string): boolean {
+  return ['javascript', 'typescript'].includes(languageId(lang))
+}
+
+export const SCRIPT_IMPORTS: Readonly<Record<string, string>> = { '@jax-js/jax': 'presmium/jax-js/index.js' }
+
+export function isTypeScript(lang: string): boolean {
+  return languageId(lang) === 'typescript'
+}

package/src/domain/index.ts

@@ -0,0 +1,11 @@
+export { configuredTimeout, DEFAULT_EXEC_CONFIG, EXEC_ID, execConfig, isPython, isScript, isTypeScript, SCRIPT_IMPORTS } from './config.ts'
+export type { ExecConfig } from './config.ts'
+export { createExecutorRouter } from './router.ts'
+export type { RouterText } from './router.ts'
+export { mimeText, outputText } from './outputs.ts'
+export { appendRun, compareRuns, defaultPair, fallbackReason, stringArgs, withRecordedFallback } from './runs.ts'
+export type { ArgChange, OutputLine, RecordedOutput, RunComparison, RunHistory, RunRecord } from './runs.ts'
+export { importableInBrowser, pythonImports } from './browser-python.ts'
+export { paramsPrelude, shownOutput } from './static-output.ts'
+export { frameAt, TRACER } from './trace.ts'
+export type { Trace, TraceEvent, TraceFrame, Tracer } from './trace.ts'

package/src/domain/outputs.ts

@@ -0,0 +1,18 @@
+import type { RunResult } from '@lincyaw/kernel'
+
+/** The text of a value of a MIME bundle: a list of lines (as nbformat splits long text) joined, other JSON printed. */
+export function mimeText(value: unknown, space?: number): string {
+  return Array.isArray(value) ? value.join('') : typeof value === 'string' ? value : value === undefined ? '' : JSON.stringify(value, null, space)
+}
+
+/** A readable projection of ordered notebook outputs, including the final expression. */
+export function outputText(result: RunResult): string {
+  if (!result.outputs || result.source === 'recorded') return result.stdout + (result.source === 'live' ? result.stderr : '')
+  return result.outputs.map((output) => {
+    if (output.output_type === 'stream') return output.text
+    if (output.output_type === 'error') return `${output.traceback.join('\n') || `${output.ename}: ${output.evalue}`}\n`
+    const data = output.data
+    const text = mimeText(data['text/plain'] ?? data['text/markdown'] ?? data['application/json'], 2)
+    return text && !text.endsWith('\n') ? `${text}\n` : text
+  }).join('')
+}

package/src/domain/router.ts

@@ -0,0 +1,50 @@
+import { errorMessage, failedRun } from '@lincyaw/kernel'
+import type { Executor, ExecutorRouter, RunRequest, RunResult } from '@lincyaw/kernel'
+
+interface Entry {
+  executor: Executor
+  priority: number
+  order: number
+}
+
+export interface RouterText {
+  noExecutor(lang: string): string
+  executorUnavailable(executor: string, lang: string): string
+  executorCrashed(executor: string, error: string): string
+}
+
+export function createExecutorRouter(text: RouterText, id = 'presmium.exec.router'): ExecutorRouter {
+  let entries: Entry[] = []
+  let registrations = 0
+  const page = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+  const scoped = (session: string) => `${session}@${page}`
+  const pick = (lang: string) => entries.find(entry => entry.executor.supports(lang))?.executor
+
+  return {
+    id,
+    supports: lang => pick(lang) !== undefined,
+    async run(request: RunRequest, signal?: AbortSignal): Promise<RunResult> {
+      const named = request.executor
+      const executor = named ? entries.find(entry => entry.executor.id === named)?.executor : pick(request.lang)
+      if (named && !executor?.supports(request.lang)) return failedRun(id, text.executorUnavailable(named, request.lang))
+      if (!executor) return failedRun(id, text.noExecutor(request.lang))
+      const started = Date.now()
+      try {
+        return await executor.run(request.session ? { ...request, session: scoped(request.session) } : request, signal)
+      } catch (error) {
+        return failedRun(executor.id, text.executorCrashed(executor.id, errorMessage(error)), Date.now() - started)
+      }
+    },
+    async endSession(session) {
+      await Promise.all(entries.map(entry => entry.executor.endSession?.(scoped(session)).catch(() => {})))
+    },
+    register(executor, priority = 0) {
+      const entry = { executor, priority, order: registrations++ }
+      entries = [...entries, entry].sort((a, b) => b.priority - a.priority || a.order - b.order)
+      return () => {
+        entries = entries.filter(e => e !== entry)
+      }
+    },
+    list: () => entries.map(entry => entry.executor),
+  }
+}

package/src/domain/runs.ts

@@ -0,0 +1,72 @@
+import type { RunResult } from '@lincyaw/kernel'
+import { diffLines } from 'diff'
+import { outputText } from './outputs.ts'
+
+export function stringArgs(params: Record<string, unknown> | undefined): Record<string, string> {
+  return Object.fromEntries(Object.entries(params ?? {}).map(([name, value]) => [name, value !== null && typeof value === 'object' ? JSON.stringify(value) : String(value)]))
+}
+
+export type RecordedOutput = string
+
+export function withRecordedFallback(result: RunResult, recorded: RecordedOutput | undefined): RunResult {
+  if (result.ok || recorded === undefined) return result
+  return { ...result, stdout: recorded, source: 'recorded' }
+}
+
+export function fallbackReason(result: RunResult): 'timedOut' | 'failed' | undefined {
+  if (result.source !== 'recorded') return undefined
+  return result.timedOut ? 'timedOut' : 'failed'
+}
+
+export interface RunRecord {
+  id: number
+  args: Record<string, string>
+  result: RunResult
+}
+
+export type RunHistory = readonly RunRecord[]
+
+export function appendRun(history: RunHistory, args: Record<string, string>, result: RunResult): RunHistory {
+  return [...history, { id: history.length + 1, args: { ...args }, result }]
+}
+
+export function defaultPair(history: RunHistory): [number, number] | undefined {
+  const n = history.length
+  return n >= 2 ? [history[n - 2]!.id, history[n - 1]!.id] : undefined
+}
+
+export interface ArgChange {
+  name: string
+  before?: string
+  after?: string
+}
+
+export interface OutputLine {
+  kind: 'same' | 'added' | 'removed'
+  text: string
+}
+
+export interface RunComparison {
+  before: RunRecord
+  after: RunRecord
+  args: ArgChange[]
+  output: OutputLine[]
+  changed: boolean
+}
+
+export function compareRuns(before: RunRecord, after: RunRecord): RunComparison {
+  const names = [...new Set([...Object.keys(before.args), ...Object.keys(after.args)])]
+  const args = names
+    .filter(name => before.args[name] !== after.args[name])
+    .map(name => ({ name, before: before.args[name], after: after.args[name] }))
+  const output = diffLines(outputText(before.result), outputText(after.result)).flatMap(change =>
+    splitLines(change.value).map((text): OutputLine => ({ kind: change.added ? 'added' : change.removed ? 'removed' : 'same', text })),
+  )
+  return { before, after, args, output, changed: output.some(line => line.kind !== 'same') }
+}
+
+function splitLines(value: string): string[] {
+  const lines = value.split('\n')
+  if (lines.at(-1) === '') lines.pop()
+  return lines
+}

package/src/domain/static-output.ts

@@ -0,0 +1,20 @@
+import type { RunResult } from '@lincyaw/kernel'
+import { isPython, isScript } from './config.ts'
+import { outputText } from './outputs.ts'
+
+function literal(value: unknown, script: boolean): string {
+  if (typeof value === 'boolean') return script ? String(value) : value ? 'True' : 'False'
+  return typeof value === 'number' ? String(value) : JSON.stringify(String(value))
+}
+
+/** Assignments of a panel's parameters, put before its code where the code is shown without running it (fallback, notebook). */
+export function paramsPrelude(lang: string, params: Record<string, unknown> | undefined): string {
+  const script = isScript(lang)
+  if (!script && !isPython(lang)) return ''
+  return Object.entries(params ?? {}).map(([name, value]) => `${script ? 'const ' : ''}${name} = ${literal(value, script)}\n`).join('')
+}
+
+export function shownOutput(runs: readonly RunResult[], recorded: string | undefined): { text: string, recorded: boolean } {
+  if (recorded !== undefined && !(runs.length > 0 && runs.every(run => run.ok))) return { text: recorded, recorded: true }
+  return { text: runs.map(outputText).join(''), recorded: false }
+}

package/src/domain/trace.ts

@@ -0,0 +1,32 @@
+import type { RunRequest } from '@lincyaw/kernel'
+import { defineService } from '@lincyaw/kernel'
+
+export interface TraceEvent {
+  line: number
+  output: string
+}
+
+export interface Trace {
+  events: TraceEvent[]
+  truncated: boolean
+  error?: string
+}
+
+export interface TraceFrame {
+  step: number
+  line?: number
+  output: string
+}
+
+export function frameAt(trace: Trace, step: number): TraceFrame {
+  const at = Math.max(0, Math.min(step, trace.events.length))
+  const event = trace.events[at - 1]
+  return { step: at, line: event?.line, output: event?.output ?? '' }
+}
+
+export interface Tracer {
+  supports(lang: string): boolean
+  trace(request: RunRequest, signal?: AbortSignal): Promise<Trace>
+}
+
+export const TRACER = defineService<Tracer>('presmium.exec.tracer')

package/src/node/browser-imports.ts

@@ -0,0 +1,34 @@
+import { componentCode, docBlocks } from '@lincyaw/kernel'
+import type { Check, CodeNode, Finding, IRBlock } from '@lincyaw/kernel'
+import { EXEC_ID, importableInBrowser, isPython, pythonImports } from '../domain/index.ts'
+
+function browserPython(block: IRBlock): CodeNode | undefined {
+  const { node } = block
+  if (node.type === 'code') {
+    const run = node.run
+    return run && run.when !== 'compile' && !run.executor && isPython(run.lang) ? node : undefined
+  }
+  if (node.type === 'component' && node.plugin === EXEC_ID && node.name === 'PmStepRun' && isPython(String(node.props.lang ?? 'python'))) return componentCode(node)
+  return undefined
+}
+
+/** Warns of Python that also runs in the browser and imports modules Pyodide does not have. */
+export const browserImportsCheck: Check = {
+  id: 'presmium.exec',
+  async run(ctx) {
+    const findings: Finding[] = []
+    for (const { block } of docBlocks(ctx.ir)) {
+      const code = browserPython(block)
+      const missing = code ? pythonImports(code.value).filter(name => !importableInBrowser(name)) : []
+      if (missing.length === 0) continue
+      findings.push({
+        checkId: 'presmium.exec',
+        severity: 'warning',
+        message: `this Python code also runs in the browser, which has the standard library only: ${missing.join(', ')} cannot be imported there`,
+        hint: 'run it at compile time only (:run: compile), or write it with the standard library',
+        source: { file: block.source.file, line: block.source.line },
+      })
+    }
+    return findings
+  },
+}

package/src/node/child-process.ts

@@ -0,0 +1,109 @@
+import { failedRun } from '@lincyaw/kernel'
+import type { RunContext, RunOutput, RunRequest, RunResult, SandboxResult } from '@lincyaw/kernel'
+import { directSandbox, minimalRunEnv, NODE_RESOURCE_ARGS, RUN_REQUEST_FILE, runResultFile } from '@lincyaw/kernel/node'
+import { DEFAULT_EXEC_CONFIG } from '../domain/index.ts'
+
+interface RunnerOutput {
+  stdout: string
+  stderr: string
+  exitCode: number
+  outputs?: RunOutput[]
+}
+
+const UNSETTLED_AWAIT = 13
+
+/** How an executor starts the child process that runs its requests: the command, the paths it reads, whether it keeps sessions. */
+export interface ChildLaunchSpec {
+  executorId: string
+  argv: string[]
+  read(): string[]
+  sessions: boolean
+}
+
+interface Pending {
+  request: RunRequest
+  signal?: AbortSignal
+  ctx?: RunContext
+  resolve(result: RunResult): void
+}
+
+interface RunSession {
+  history: RunRequest[]
+  queue: Pending[]
+  tail: Promise<void>
+}
+
+/**
+ * Runs requests in a child process, in the process sandbox when one is configured: requests of a session that arrive
+ * together go into one run, and a later one first runs the session's earlier requests again.
+ */
+export function createChildProcessRuns(launch: ChildLaunchSpec) {
+  const runSessions = new Map<string, RunSession>()
+
+  async function batch(requests: RunRequest[], skip: number, signal?: AbortSignal, ctx?: RunContext): Promise<RunResult[]> {
+    const id = launch.executorId
+    const session = launch.sessions ? requests[0]?.session : undefined
+    const input = { session, runs: requests.map(({ code, args, stdin, files, lang }) => ({ code, args, stdin, files, lang })) }
+    const timeouts = requests.map(r => r.timeoutMs ?? DEFAULT_EXEC_CONFIG.timeoutMs)
+    const timeoutMs = timeouts.reduce((sum, t) => sum + t, 0)
+    const sandbox = ctx?.sandbox ?? directSandbox
+    const started = Date.now()
+    let outcome: SandboxResult
+    try {
+      outcome = await sandbox.run({
+        argv: launch.argv[0] === process.execPath ? [process.execPath, ...NODE_RESOURCE_ARGS, ...launch.argv.slice(1)] : launch.argv,
+        files: { [RUN_REQUEST_FILE]: JSON.stringify(input) },
+        collect: requests.map((_, i) => runResultFile(i)),
+        env: ctx?.env ?? minimalRunEnv(),
+        read: launch.read(),
+        timeoutMs,
+        signal,
+      })
+    } catch (error) {
+      return requests.slice(skip).map(() => failedRun(id, `the ${sandbox.kind} sandbox failed: ${error instanceof Error ? error.message : String(error)}`, Date.now() - started))
+    }
+    const durationMs = Date.now() - started
+    let missing = false
+    return requests.map((_, i): RunResult => {
+      const file = outcome.files[runResultFile(i)]
+      let output: RunnerOutput | undefined
+      try {
+        output = file ? JSON.parse(Buffer.from(file).toString('utf8')) as RunnerOutput : undefined
+      } catch {}
+      if (output) return { ok: output.exitCode === 0, stdout: output.stdout, stderr: output.stderr, exitCode: output.exitCode, durationMs, timedOut: false, source: 'live', executorId: id, ...output.outputs ? { outputs: output.outputs } : {} }
+      const first = !missing
+      missing = true
+      if (!first) return failedRun(id, 'Not run: an earlier block of the session did not finish', durationMs)
+      if (outcome.exitCode === null && !signal?.aborted) return { ...failedRun(id, `Stopped after ${timeouts.slice(0, i + 1).reduce((sum, t) => sum + t, 0)} ms`, durationMs), timedOut: true }
+      if (outcome.exitCode === UNSETTLED_AWAIT) return { ...failedRun(id, 'The program ended while a top-level await was still pending', durationMs), exitCode: outcome.exitCode }
+      return failedRun(id, outcome.stderr || `the ${id} runner produced no result`, durationMs)
+    }).slice(skip)
+  }
+
+  async function flush(state: RunSession): Promise<void> {
+    const queue = state.queue
+    state.queue = []
+    const skip = state.history.length
+    const requests = [...state.history, ...queue.map(p => p.request)]
+    const results = await batch(requests, skip, queue[0]?.signal, queue[0]?.ctx)
+    state.history = requests
+    queue.forEach((pending, i) => pending.resolve(results[i]!))
+  }
+
+  return {
+    run(request: RunRequest, signal?: AbortSignal, ctx?: RunContext): Promise<RunResult> {
+      const name = launch.sessions ? request.session : undefined
+      if (!name) return batch([request], 0, signal, ctx).then(results => results[0]!)
+      let state = runSessions.get(name)
+      if (!state) runSessions.set(name, state = { history: [], queue: [], tail: Promise.resolve() })
+      const runSession = state
+      return new Promise((resolve) => {
+        runSession.queue.push({ request, signal, ctx, resolve })
+        if (runSession.queue.length === 1) runSession.tail = runSession.tail.then(() => new Promise(next => setImmediate(next))).then(() => flush(runSession))
+      })
+    },
+    async endSession(session: string): Promise<void> {
+      runSessions.delete(session)
+    },
+  }
+}

package/src/node/code-component.ts

@@ -0,0 +1,48 @@
+import type { CodeNode, ComponentNode, DirectiveContext, DirectiveInput, IRBlock, RunSpec } from '@lincyaw/kernel'
+import { parse } from 'yaml'
+import { configuredTimeout, EXEC_ID, isPython, isScript, stringArgs } from '../domain/index.ts'
+
+type Params = Record<string, unknown>
+
+function params(value: unknown, lang: string, ctx: DirectiveContext): Params | undefined {
+  if (value === undefined) return undefined
+  let data = value
+  try {
+    if (typeof value === 'string') data = parse(value)
+  }
+  catch {}
+  const variables = isPython(lang) || isScript(lang)
+  if (data !== null && typeof data === 'object' && !Array.isArray(data)
+    && (!variables || Object.values(data).every(v => ['string', 'number', 'boolean'].includes(typeof v)))) {
+    return data as Params
+  }
+  ctx.report({ checkId: 'presmium.exec.syntax', severity: 'error', message: variables ? ':params: must be a mapping of names to values, e.g. {n: 5}' : ':params: must be a mapping, e.g. {n: 5}' })
+  return undefined
+}
+
+function positive(value: unknown): number | undefined {
+  const n = Number(value)
+  return value !== undefined && Number.isFinite(n) && n > 0 ? n : undefined
+}
+
+/** The component of a directive whose body is code (the run panel, the step run), with the code as its child block. */
+export function codeComponent(name: string, input: DirectiveInput, ctx: DirectiveContext, run?: Omit<RunSpec, 'lang'>): ComponentNode {
+  const lang = input.arg?.trim() || 'python'
+  const value = input.body.replace(/\n+$/, '')
+  const props: Record<string, unknown> = { lang, code: value }
+  const values = params(input.options.params, lang, ctx)
+  if (values) props.params = values
+  const timeout = positive(input.options.timeout) ?? configuredTimeout(ctx.config)
+  if (timeout) props.timeout = timeout
+  const code: CodeNode = { type: 'code', lang, value }
+  if (run) code.run = { lang, ...run, ...values ? { args: stringArgs(values) } : {}, ...timeout ? { timeoutMs: timeout } : {} }
+  const source: IRBlock = { id: 'source', role: 'visual', at: 0, source: ctx.source, node: code }
+  return {
+    type: 'component',
+    plugin: EXEC_ID,
+    name,
+    props,
+    children: [source],
+    fallback: { type: 'root', children: [{ type: 'code', lang, value }] },
+  }
+}