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

package/src/domain/outputs.ts

@@ -0,0 +1,89 @@
+import { isRecord } from '@lincyaw/kernel'
+import type { RunOutput } from '@lincyaw/kernel'
+
+const ANSI = /\u001B\[[0-9;?]*[ -/]*[@-~]/g
+
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI, '')
+}
+
+export class OutputCollector {
+  readonly outputs: RunOutput[] = []
+  #ids: (string | undefined)[] = []
+  #clearOnNext = false
+
+  add(type: string, content: unknown): void {
+    if (!isRecord(content)) return
+    if (type === 'clear_output') {
+      if (content.wait === true) this.#clearOnNext = true
+      else this.#clear()
+      return
+    }
+    if (type === 'update_display_data') {
+      const id = displayId(content)
+      const output = richOutput('display_data', content)
+      this.#ids.forEach((known, i) => {
+        if (id !== undefined && known === id && output) this.outputs[i] = output
+      })
+      return
+    }
+    const output = type === 'stream'
+      ? streamOutput(content)
+      : type === 'display_data' || type === 'execute_result'
+        ? richOutput(type, content)
+        : type === 'error'
+          ? errorOutput(content)
+          : undefined
+    if (!output) return
+    if (this.#clearOnNext) {
+      this.#clear()
+      this.#clearOnNext = false
+    }
+    const last = this.outputs.at(-1)
+    if (output.output_type === 'stream' && last?.output_type === 'stream' && last.name === output.name) {
+      this.outputs[this.outputs.length - 1] = { ...last, text: last.text + output.text }
+      return
+    }
+    this.outputs.push(output)
+    this.#ids.push(type === 'display_data' ? displayId(content) : undefined)
+  }
+
+  text(): { stdout: string, stderr: string } {
+    let stdout = ''
+    let stderr = ''
+    for (const output of this.outputs) {
+      if (output.output_type === 'stream') {
+        if (output.name === 'stdout') stdout += output.text
+        else stderr += output.text
+      } else if (output.output_type === 'error') {
+        stderr += `${stripAnsi(output.traceback.join('\n'))}\n`
+      }
+    }
+    return { stdout, stderr }
+  }
+
+  #clear(): void {
+    this.outputs.length = 0
+    this.#ids = []
+  }
+}
+
+function displayId(content: Record<string, unknown>): string | undefined {
+  const transient = content.transient
+  return isRecord(transient) && typeof transient.display_id === 'string' ? transient.display_id : undefined
+}
+
+function streamOutput(content: Record<string, unknown>): RunOutput | undefined {
+  if (typeof content.text !== 'string') return undefined
+  return { output_type: 'stream', name: content.name === 'stderr' ? 'stderr' : 'stdout', text: content.text }
+}
+
+function richOutput(type: 'display_data' | 'execute_result', content: Record<string, unknown>): RunOutput | undefined {
+  if (!isRecord(content.data)) return undefined
+  return { output_type: type, data: content.data, ...isRecord(content.metadata) && Object.keys(content.metadata).length ? { metadata: content.metadata } : {} }
+}
+
+function errorOutput(content: Record<string, unknown>): RunOutput {
+  const traceback = Array.isArray(content.traceback) ? content.traceback.filter((line): line is string => typeof line === 'string') : []
+  return { output_type: 'error', ename: String(content.ename ?? 'Error'), evalue: String(content.evalue ?? ''), traceback }
+}

package/src/domain/terminal-service.ts

@@ -0,0 +1,21 @@
+import { defineService } from '@lincyaw/kernel'
+
+export interface TerminalSession {
+  send(data: string): void
+  resize(rows: number, columns: number): void
+  close(): Promise<void>
+  abandon(): void
+}
+
+export interface TerminalEvents {
+  output(data: string): void
+  closed(): void
+}
+
+/** Terminals of the deck's Jupyter environments, for PmTerminal. */
+export interface JupyterTerminals {
+  unavailable(name: string): string | undefined
+  openTerminal(name: string, events: TerminalEvents): Promise<TerminalSession>
+}
+
+export const JUPYTER_TERMINALS = defineService<JupyterTerminals>('presmium.execJupyter.environments')

package/src/node/connection.ts

@@ -0,0 +1,45 @@
+import type { ServerConnection } from '@jupyterlab/services'
+import WebSocket from 'ws'
+import type { ClientOptions } from 'ws'
+import type { Connection } from '../domain/connection.ts'
+import { loadJupyterServices } from '../shared/load-services.ts'
+
+let quiet = false
+
+function quietSockets(): void {
+  if (quiet) return
+  quiet = true
+  const debug = console.debug.bind(console)
+  console.debug = (...args: unknown[]) => {
+    if (typeof args[0] === 'string' && /^(?:Starting WebSocket|Kernel): /.test(args[0])) return
+    debug(...args)
+  }
+}
+
+/** Settings of a connection from Node: `ws` WebSockets and `fetch`, both with the connection's headers. */
+export async function nodeSettings(connection: Connection, signal?: AbortSignal): Promise<ServerConnection.ISettings> {
+  quietSockets()
+  const { ServerConnection } = await loadJupyterServices()
+  const headers = connection.headers
+  class HeaderSocket extends WebSocket {
+    constructor(url: string, protocols?: string | string[], options?: ClientOptions) {
+      super(url, protocols, { ...options, headers: { ...options?.headers, ...headers } })
+    }
+  }
+  return ServerConnection.makeSettings({
+    baseUrl: connection.url,
+    wsUrl: connection.url.replace(/^http/, 'ws'),
+    token: '',
+    appendToken: false,
+    WebSocket: HeaderSocket as unknown as typeof globalThis.WebSocket,
+    fetch: async (input: RequestInfo | URL, init?: RequestInit) => {
+      const request = new Request(input, init)
+      for (const [name, value] of Object.entries(headers)) request.headers.set(name, value)
+      return fetch(request, signal ? { signal: AbortSignal.any([request.signal, signal]) } : undefined).catch((error: unknown) => {
+        const cause = (error as { cause?: { code?: unknown, message?: unknown } }).cause
+        const detail = typeof cause?.code === 'string' ? cause.code : typeof cause?.message === 'string' ? cause.message : undefined
+        throw detail && error instanceof Error ? new TypeError(`${error.message} (${detail})`) : error
+      })
+    },
+  })
+}

package/src/node/declared.ts

@@ -0,0 +1,16 @@
+import type { EnvironmentSpec, IRPass } from '@lincyaw/kernel'
+import { jupyterSpecs } from '../domain/index.ts'
+
+const declared = new Map<string, ReadonlyMap<string, EnvironmentSpec>>()
+
+/** The `kind: jupyter` environments of the deck's latest compile, which the server's proxies follow. */
+export function declaredEnvironments(deckDir: string): ReadonlyMap<string, EnvironmentSpec> {
+  return declared.get(deckDir) ?? new Map()
+}
+
+export const declaredEnvironmentsPass: IRPass = {
+  name: 'presmium.execJupyter.environments',
+  run(doc, ctx) {
+    declared.set(ctx.deckDir, new Map(Object.entries(jupyterSpecs(doc.config.execute?.environments))))
+  },
+}

package/src/node/hub.ts

@@ -0,0 +1,68 @@
+import { isRecord } from '@lincyaw/kernel'
+import type { EnvironmentSpec } from '@lincyaw/kernel'
+import type { Connection, OperatorSide } from '../domain/index.ts'
+
+export class HubEnvironmentError extends Error {
+  readonly code: string
+  readonly status: number
+  constructor(code: string, status = 502) { super(code); this.code = code; this.status = status }
+}
+
+/** Only operator-supplied addresses and the current owner's scoped token can reach the Hub. */
+export async function prepareHubEnvironment(spec: EnvironmentSpec, side: OperatorSide, signal: AbortSignal): Promise<{ connection: Connection, generation: string }> {
+  if (typeof spec.profile !== 'string' || !/^[a-z][a-z0-9-]{0,31}$/.test(spec.profile) || spec.url || spec.image) {
+    throw new HubEnvironmentError('hub-profile-unavailable', 422)
+  }
+  const api = side.secret('JUPYTERHUB_API_URL')?.replace(/\/+$/, '')
+  const proxy = side.secret('PRESMIUM_HUB_PROXY_URL')?.replace(/\/+$/, '')
+  const token = side.secret('JUPYTERHUB_API_TOKEN')
+  const user = side.secret('JUPYTERHUB_USER')
+  if (!api || !proxy || !token || !user || ![api, proxy].every(value => /^https?:\/\//.test(value))) {
+    throw new HubEnvironmentError('hub-not-configured', 503)
+  }
+  const profiles: unknown = JSON.parse(side.secret('PRESMIUM_HUB_PROFILES') || '[]')
+  if (!Array.isArray(profiles) || !profiles.includes(spec.profile)) throw new HubEnvironmentError('hub-profile-unavailable', 422)
+  const server = `env-${spec.profile}`
+  const path = `/users/${encodeURIComponent(user)}`
+  const headers = { Authorization: `token ${token}` }
+  const request = (suffix: string, method = 'GET') => fetch(`${api}${path}${suffix}`, {
+    method, headers, redirect: 'manual', signal: AbortSignal.any([signal, AbortSignal.timeout(30_000)]),
+  })
+  const state = async () => {
+    const response = await request('')
+    if (!response.ok) throw new HubEnvironmentError('hub-unavailable')
+    const value: unknown = await response.json()
+    const servers = isRecord(value) && isRecord(value.servers) ? value.servers : {}
+    const found = servers[server]
+    return isRecord(found) ? found : undefined
+  }
+  let current = await state()
+  if (!current || (!current.ready && !current.pending)) {
+    const response = await request(`/servers/${server}`, 'POST')
+    if (!response.ok) {
+      // Another document may have started this user's same profile concurrently.
+      current = await state()
+      if (!current?.ready && current?.pending !== 'spawn') {
+        throw new HubEnvironmentError(response.status === 400 ? 'hub-profile-unavailable' : 'hub-start-failed')
+      }
+    }
+  }
+  const until = Date.now() + 240_000
+  for (;;) {
+    signal.throwIfAborted()
+    current = await state()
+    if (current?.ready) {
+      return {
+        connection: { url: `${proxy}/user/${encodeURIComponent(user)}/${server}/`, headers },
+        generation: typeof current.started === 'string' ? current.started : '',
+      }
+    }
+    if (!current || (!current.pending && current.stopped)) throw new HubEnvironmentError('hub-start-failed')
+    if (Date.now() >= until) throw new HubEnvironmentError('hub-start-timeout', 504)
+    await new Promise<void>((resolve, reject) => {
+      const abort = () => { clearTimeout(timer); reject(signal.reason) }
+      const timer = setTimeout(() => { signal.removeEventListener('abort', abort); resolve() }, 500)
+      signal.addEventListener('abort', abort, { once: true })
+    })
+  }
+}

package/src/node/presmium.ts

@@ -0,0 +1,24 @@
+import { createRequire } from 'node:module'
+import type { PresmiumNodePlugin } from '@lincyaw/kernel'
+import { EXEC_JUPYTER_ID } from '../domain/index.ts'
+import { declaredEnvironmentsPass } from './declared.ts'
+import { jupyterProvider } from './provider.ts'
+import { jupyterProxy } from './proxy.ts'
+import { terminalDirective, terminalPass } from './terminal.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+const plugin: PresmiumNodePlugin = {
+  id: EXEC_JUPYTER_ID,
+  version,
+  kernel: '^1.0.0',
+  directives: [terminalDirective],
+  passes: [declaredEnvironmentsPass, terminalPass],
+  environments: { jupyter: jupyterProvider },
+  server: jupyterProxy,
+  rendererExtensions: {
+    notebook: { components: { PmTerminal: () => [] } },
+  },
+}
+
+export default plugin

package/src/node/provider.ts

@@ -0,0 +1,85 @@
+import { createHash } from 'node:crypto'
+import { environmentExecutor } from '@lincyaw/kernel'
+import type { EnvironmentContext, EnvironmentProvider, EnvironmentSpec, Executor } from '@lincyaw/kernel'
+import { jupyterKernelName, languagesOf, operatorConnection } from '../domain/index.ts'
+import { createJupyterKernels } from '../shared/kernels.ts'
+import type { JupyterKernels, JupyterKernelsText } from '../shared/kernels.ts'
+import { nodeSettings } from './connection.ts'
+
+const FINGERPRINT_TTL_MS = 60_000
+
+function nodeText(prefix: string, url: () => string): JupyterKernelsText {
+  return {
+    unreachable: error => `${prefix}cannot reach ${url()}: ${error}`,
+    refused: `${prefix}the server at ${url()} refused the token`,
+    noKernel: (kernel, known) => `${prefix}the server has no kernel ${kernel} (it has ${known.join(', ') || 'none'})`,
+    wrongLanguage: (kernel, language, lang) => `${prefix}kernel ${kernel} runs ${language}, not ${lang}`,
+    timedOut: seconds => `${prefix}timed out after ${seconds} s; the kernel was interrupted`,
+  }
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`).join(',')}}`
+  return JSON.stringify(value)
+}
+
+function createJupyterExecutor(name: string, spec: EnvironmentSpec, ctx: EnvironmentContext): Executor {
+  const id = environmentExecutor(name)
+  const kernelName = jupyterKernelName(spec)
+  const languages = languagesOf(spec)
+  let kernels: JupyterKernels | undefined
+  const pool = (): JupyterKernels => {
+    if (kernels) return kernels
+    const resolved = operatorConnection(name, spec, { secret: ctx.secret })
+    return kernels = createJupyterKernels({
+      executorId: id,
+      kernelName,
+      languages,
+      settings: () => 'connection' in resolved
+        ? nodeSettings(resolved.connection)
+        : Promise.reject(new Error(`environment "${name}": ${'unavailable' in resolved ? resolved.unavailable : resolved.mismatch}`)),
+      cleanupFailed: error => ctx.log.warn(`environment "${name}": Jupyter cleanup failed`, error),
+      text: nodeText(`environment "${name}": `, () => ('connection' in resolved ? resolved.connection.url : '')),
+    })
+  }
+  let fingerprint: { at: number, value: Promise<string> } | undefined
+
+  return {
+    id,
+    supports: lang => pool().supports(lang),
+    run: (request, signal) => pool().run(request, signal),
+    async endSession(session) {
+      await kernels?.endSession(session)
+    },
+    fingerprint() {
+      if (!fingerprint || Date.now() - fingerprint.at > FINGERPRINT_TTL_MS) {
+        const value = pool().describe().then((described) => {
+          const specHash = createHash('sha256').update(canonical(described.spec)).digest('hex').slice(0, 16)
+          const image = typeof spec.image === 'string' && spec.image ? spec.image : 'unpinned'
+          return `jupyter image=${image} kernelspec=${kernelName}:sha256:${specHash} kernel=${described.implementation} ${described.implementationVersion} ${described.language} ${described.languageVersion}`
+        })
+        fingerprint = { at: Date.now(), value }
+        value.catch(() => {
+          if (fingerprint?.value === value) fingerprint = undefined
+        })
+      }
+      return fingerprint.value
+    },
+  }
+}
+
+export const jupyterProvider: EnvironmentProvider = {
+  create(name, spec, ctx) {
+    const resolved = operatorConnection(name, spec, { secret: ctx.secret })
+    if ('mismatch' in resolved) throw new Error(resolved.mismatch)
+    return createJupyterExecutor(name, spec, ctx)
+  },
+  async probe(name, spec, ctx) {
+    const resolved = operatorConnection(name, spec, { secret: ctx.secret })
+    if (!('connection' in resolved)) return 'unavailable' in resolved ? resolved.unavailable : resolved.mismatch
+    const { connection } = resolved
+    const kernels = createJupyterKernels({ executorId: environmentExecutor(name), kernelName: jupyterKernelName(spec), settings: () => nodeSettings(connection), text: nodeText('', () => connection.url) })
+    return kernels.probe()
+  },
+}

package/src/node/proxy.ts

@@ -0,0 +1,141 @@
+import { isRecord, jsonResponse, problemResponse } from '@lincyaw/kernel'
+import type { EnvironmentSpec, ProxySpec, Route, ServerContext, ServerContribution } from '@lincyaw/kernel'
+import { authOf, cleanupPath, operatorConnection, preparePath, proxyPath } from '../domain/index.ts'
+import type { Connection } from '../domain/index.ts'
+import { shutdownJupyterKernel } from '../shared/kernel-lifecycle.ts'
+import { nodeSettings } from './connection.ts'
+import { declaredEnvironments } from './declared.ts'
+import { HubEnvironmentError, prepareHubEnvironment } from './hub.ts'
+
+function proxyHeaders(connection: Connection): Record<string, string> {
+  const target = new URL(connection.url)
+  const headers: Record<string, string> = { host: target.host, origin: target.origin }
+  for (const [name, value] of Object.entries(connection.headers)) headers[name.toLowerCase()] = value
+  return headers
+}
+
+interface Mount {
+  proxy?: ProxySpec
+  connection?: Connection
+  reason?: string
+}
+
+/** The server's proxy to each `auth: proxy` environment, and the route through which a page hands over its kernels' cleanup. */
+export function jupyterProxy(ctx: ServerContext): ServerContribution {
+  const reported = new Set<string>()
+  const cleaning = new Map<string, Promise<void>>()
+  const prepared = new Map<string, { profile: unknown, connection: Connection }>()
+  const preparing = new Map<string, Promise<{ connection: Connection, generation: string }>>()
+  const lifetime = new AbortController()
+  const hubKey = (name: string, spec: EnvironmentSpec) => JSON.stringify([name, spec.profile])
+  const mounts = (): Map<string, Mount> => {
+    const found = new Map<string, Mount>()
+    for (const [name, spec] of declaredEnvironments(ctx.deckDir)) {
+      if (!['proxy', 'hub'].includes(authOf(spec))) continue
+      found.set(name, mount(name, spec))
+    }
+    return found
+  }
+  const mount = (name: string, spec: EnvironmentSpec): Mount => {
+    if (authOf(spec) === 'hub') {
+      const known = prepared.get(hubKey(name, spec))
+      if (!known || known.profile !== spec.profile) return { reason: 'hub-environment-not-prepared' }
+      return { connection: known.connection, proxy: { path: proxyPath(name), target: known.connection.url, headers: proxyHeaders(known.connection), role: 'reader' } }
+    }
+    const resolved = operatorConnection(name, spec, { secret: name => ctx.secret(name) })
+    if ('connection' in resolved) {
+      return { connection: resolved.connection, proxy: { path: proxyPath(name), target: resolved.connection.url, headers: proxyHeaders(resolved.connection), role: 'reader' } }
+    }
+    const reason = `environment "${name}": ${'unavailable' in resolved ? resolved.unavailable : resolved.mismatch}`
+    if (!reported.has(reason)) {
+      reported.add(reason)
+      ctx.log.error(`${reason}; its proxy is not mounted`)
+    }
+    return { reason }
+  }
+  return {
+    get proxies() {
+      return [...mounts().values()].flatMap(found => (found.proxy ? [found.proxy] : []))
+    },
+    get routes() {
+      const routes: Record<string, Route> = {}
+      for (const [name, spec] of declaredEnvironments(ctx.deckDir)) {
+        if (authOf(spec) !== 'hub') continue
+        routes[preparePath(name)] = {
+          role: 'reader',
+          maxBody: 1024,
+          async handle(request) {
+            if (request.method !== 'POST') return problemResponse(405, 'POST')
+            if (lifetime.signal.aborted) return problemResponse(503, 'hub-unavailable')
+            const key = hubKey(name, spec)
+            let task = preparing.get(key)
+            if (!task) {
+              // Shared starts outlive one disconnected tab, but are always bounded.
+              if (preparing.size >= 32) return problemResponse(429, 'hub-unavailable')
+              task = prepareHubEnvironment(spec, { secret: name => ctx.secret(name) }, AbortSignal.any([lifetime.signal, AbortSignal.timeout(250_000)]))
+                .finally(() => preparing.delete(key))
+              preparing.set(key, task)
+            }
+            try {
+              const { connection, generation } = await task
+              const current = declaredEnvironments(ctx.deckDir).get(name)
+              if (lifetime.signal.aborted || !current || authOf(current) !== 'hub' || current.profile !== spec.profile) {
+                return problemResponse(409, 'hub-profile-changed')
+              }
+              prepared.set(key, { profile: spec.profile, connection })
+              return jsonResponse({ generation })
+            } catch (error) {
+              prepared.delete(key)
+              const code = error instanceof HubEnvironmentError ? error.code : 'hub-unavailable'
+              ctx.log.warn(`environment "${name}": ${code}`)
+              return problemResponse(error instanceof HubEnvironmentError ? error.status : 502, code)
+            }
+          },
+        }
+      }
+      for (const [name, found] of mounts()) {
+        if (found.connection) {
+          const connection = found.connection
+          // Outside the proxy prefix: proxy routing takes precedence over routes.
+          routes[cleanupPath(name)] = {
+            role: 'reader',
+            maxBody: 1024,
+            async handle(request) {
+              if (request.method !== 'POST') return problemResponse(405, 'POST')
+              const body: unknown = await request.json().catch(() => undefined)
+              if (!isRecord(body) || Object.keys(body).length !== 2
+                || typeof body.kernel !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(body.kernel)
+                || typeof body.directory !== 'string' || !/^presmium-runs\/[a-z0-9]+-[a-z0-9]+$/.test(body.directory)) {
+                return problemResponse(400, 'expected a kernel id and its presmium-runs directory')
+              }
+              const key = JSON.stringify([connection.url, body.kernel, body.directory])
+              let task = cleaning.get(key)
+              if (!task) {
+                if (cleaning.size >= 32) return problemResponse(429, 'too many Jupyter cleanups in progress')
+                const { kernel, directory } = body
+                // Do not bind to request.signal: the browser may already be gone.
+                const timeout = AbortSignal.timeout(15_000)
+                task = nodeSettings(connection, timeout).then(settings => shutdownJupyterKernel(kernel, directory, settings))
+                  .finally(() => cleaning.delete(key))
+                cleaning.set(key, task)
+              }
+              await task
+              return new Response(null, { status: 204 })
+            },
+          }
+        }
+        if (!found.reason) continue
+        const reason = found.reason
+        routes[`${proxyPath(name)}/*`] = {
+          role: 'reader',
+          handle: () => problemResponse(502, reason),
+        }
+      }
+      return routes
+    },
+    async close() {
+      lifetime.abort()
+      await Promise.allSettled([...cleaning.values(), ...preparing.values()])
+    },
+  }
+}

package/src/node/terminal.ts

@@ -0,0 +1,44 @@
+import { docBlocks } from '@lincyaw/kernel'
+import type { ComponentNode, DirectiveSpec, IRPass } from '@lincyaw/kernel'
+import { DEFAULT_TERMINAL_ROWS, EXEC_JUPYTER_ID, jupyterSpecs, terminalFallback } from '../domain/index.ts'
+
+export const terminalDirective: DirectiveSpec = {
+  name: 'terminal',
+  arg: true,
+  body: false,
+  options: { height: 'number' },
+  toIR(input, ctx) {
+    const env = input.arg?.trim() ?? ''
+    if (!env) ctx.report({ checkId: EXEC_JUPYTER_ID, severity: 'error', message: '{terminal} needs the name of a kind: jupyter environment of execute.environments, e.g. :::{terminal} gpu' })
+    const height = input.options.height
+    const rows = typeof height === 'number' && Number.isInteger(height) && height > 0 ? height : DEFAULT_TERMINAL_ROWS
+    const node: ComponentNode = {
+      type: 'component',
+      plugin: EXEC_JUPYTER_ID,
+      name: 'PmTerminal',
+      props: { env, rows },
+      fallback: { type: 'root', children: [{ type: 'paragraph', children: [{ type: 'text', value: terminalFallback(env, ctx.lang) }] }] },
+    }
+    return { node }
+  },
+}
+
+export const terminalPass: IRPass = {
+  name: 'presmium.execJupyter.terminals',
+  run(doc, ctx) {
+    const declared = jupyterSpecs(doc.config.execute?.environments)
+    for (const { block } of docBlocks(doc)) {
+      const node = block.node
+      if (node.type !== 'component' || node.plugin !== EXEC_JUPYTER_ID || node.name !== 'PmTerminal') continue
+      const env = String(node.props.env ?? '')
+      if (!env || declared[env]) continue
+      const other = doc.config.execute?.environments?.[env]
+      ctx.report({
+        checkId: EXEC_JUPYTER_ID,
+        severity: 'error',
+        message: other ? `{terminal} ${env}: the environment is of kind ${other.kind}; a terminal needs kind: jupyter` : `{terminal} ${env}: no such environment in execute.environments of the headmatter`,
+        source: { file: block.source.file, line: block.source.line },
+      })
+    }
+  },
+}

package/src/node/vite.ts

@@ -0,0 +1,15 @@
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+
+/** `@jupyterlab/services` imports `ws`; in every bundle (the server-side rendering too) it gets the package's own shim. */
+export function jupyterWsShim(): { name: string, enforce: 'pre', resolveId(source: string, importer?: string): string | undefined } {
+  const shim = require.resolve('@jupyterlab/services/lib/shim/ws.js')
+  return {
+    name: 'presmium:exec-jupyter-services',
+    enforce: 'pre',
+    resolveId(source, importer) {
+      return source === 'ws' && importer?.includes('/@jupyterlab/services/') ? shim : undefined
+    },
+  }
+}

package/src/shared/execute.ts

@@ -0,0 +1,70 @@
+import type { ServerConnection } from '@jupyterlab/services'
+import type { OutputCollector } from '../domain/outputs.ts'
+import type { JupyterKernelHandle } from './kernel-lifecycle.ts'
+import { loadJupyterServices } from './load-services.ts'
+
+const INTERRUPT_GRACE_MS = 5_000
+
+/** Writes the run's files into the kernel's directory through the Contents API. */
+export async function writeRunFiles(handle: JupyterKernelHandle, settings: ServerConnection.ISettings, files: Record<string, string>): Promise<void> {
+  const { Drive } = await loadJupyterServices()
+  const drive = new Drive({ serverSettings: settings })
+  for (const [path, content] of Object.entries(files)) {
+    const parts = path.split('/').filter(Boolean)
+    if (parts.length === 0 || parts.some(part => part === '..' || part === '.')) continue
+    for (let i = 1; i < parts.length; i++) await drive.save(`${handle.dir}/${parts.slice(0, i).join('/')}`, { type: 'directory' })
+    await drive.save(`${handle.dir}/${parts.join('/')}`, { type: 'file', format: 'text', content })
+  }
+}
+
+export interface ExecuteOptions {
+  stdin: string
+  /** Collects the outputs; without it the code runs silently. */
+  collector?: OutputCollector
+  timeoutMs: number
+  signal?: AbortSignal
+  shutdown(): Promise<void>
+}
+
+/**
+ * Executes code on the kernel, answering its input requests with the lines of `stdin`. Past the timeout, or on abort,
+ * it interrupts the kernel, and shuts the kernel down if it is still busy after a grace period.
+ */
+export async function executeCode(handle: JupyterKernelHandle, code: string, options: ExecuteOptions): Promise<{ status: string, timedOut: boolean }> {
+  const { KernelAPI } = await loadJupyterServices()
+  const { collector, signal } = options
+  signal?.throwIfAborted()
+  const lines = options.stdin ? options.stdin.replace(/\n$/, '').split('\n') : []
+  const future = handle.connection.requestExecute({ code, silent: !collector, store_history: false, allow_stdin: true, stop_on_error: true })
+  future.onIOPub = (msg) => {
+    collector?.add(msg.header.msg_type, msg.content)
+  }
+  future.onStdin = (msg) => {
+    if (msg.header.msg_type === 'input_request') handle.connection.sendInputReply({ status: 'ok', value: lines.shift() ?? '' }, msg.header as never)
+  }
+  let timedOut = false
+  let stopping: ReturnType<typeof setTimeout> | undefined
+  const interrupt = () => {
+    if (stopping) return
+    void KernelAPI.interruptKernel(handle.id, handle.connection.serverSettings).catch(() => {})
+    stopping = setTimeout(() => void options.shutdown().catch(() => {}), INTERRUPT_GRACE_MS)
+  }
+  const timer = setTimeout(() => {
+    timedOut = true
+    interrupt()
+  }, options.timeoutMs)
+  const abort = () => interrupt()
+  signal?.addEventListener('abort', abort, { once: true })
+  try {
+    const reply = await future.done
+    return { status: reply.content.status, timedOut }
+  } catch (error) {
+    if (timedOut) return { status: 'error', timedOut }
+    throw error
+  } finally {
+    clearTimeout(timer)
+    clearTimeout(stopping)
+    signal?.removeEventListener('abort', abort)
+    future.dispose()
+  }
+}