Skip to main content

glass_dev/
kernels.rs

1//! Named persistent execution kernels for Glass Dev.
2
3use rusqlite::types::ValueRef;
4use serde::{Deserialize, Serialize};
5use serde_json::{Value, json};
6use std::collections::{BTreeMap, BTreeSet};
7use std::fmt;
8use std::io::{BufRead, BufReader, Write};
9use std::path::{Path, PathBuf};
10use std::process::{Child, ChildStdin, Command, Stdio};
11use std::sync::mpsc::{self, Receiver, RecvTimeoutError, TrySendError};
12use std::thread::JoinHandle;
13use std::time::{Duration, Instant};
14
15const MAX_KERNEL_OUTPUT_BYTES: usize = 1024 * 1024;
16const MAX_KERNEL_CODE_BYTES: usize = 512 * 1024;
17const MAX_KERNEL_SESSIONS: usize = 32;
18const MAX_KERNEL_MESSAGES: usize = 64;
19const MAX_KERNEL_TOOL_CALLS: usize = 32;
20const DEFAULT_KERNEL_TIMEOUT: Duration = Duration::from_secs(30);
21
22const PYTHON_WORKER: &str = r#"
23import ast, contextlib, io, json, sys, traceback
24class GlassBindings:
25    def __init__(self): self.sequence = 0
26    def call(self, tool, arguments=None):
27        self.sequence += 1
28        request_id = "python-%d" % self.sequence
29        sys.__stdout__.write(json.dumps({"kind":"toolCall", "id":request_id, "tool":tool, "arguments":arguments or {}}, ensure_ascii=True) + "\n")
30        sys.__stdout__.flush()
31        response = json.loads(sys.__stdin__.readline())
32        if response.get("kind") != "toolResult" or response.get("id") != request_id:
33            raise RuntimeError("invalid Glass tool response")
34        if not response.get("ok"):
35            raise RuntimeError(response.get("error", "Glass tool call failed"))
36        return response.get("result")
37state = {"__name__": "__glass_kernel__"}
38state["glass"] = GlassBindings()
39for line in sys.stdin:
40    try:
41        request = json.loads(line)
42        source = request["code"]
43        output = io.StringIO()
44        result = None
45        with contextlib.redirect_stdout(output), contextlib.redirect_stderr(output):
46            tree = ast.parse(source, mode="exec")
47            if tree.body and isinstance(tree.body[-1], ast.Expr):
48                prefix = ast.Module(body=tree.body[:-1], type_ignores=[])
49                exec(compile(prefix, "<glass>", "exec"), state, state)
50                result = eval(compile(ast.Expression(tree.body[-1].value), "<glass>", "eval"), state, state)
51            else:
52                exec(compile(tree, "<glass>", "exec"), state, state)
53        response = {"kind":"executionResult", "ok": True, "output": output.getvalue(), "value": repr(result) if result is not None else None}
54    except Exception:
55        response = {"kind":"executionResult", "ok": False, "output": "", "error": traceback.format_exc(limit=16)}
56    print(json.dumps(response, ensure_ascii=True), flush=True)
57"#;
58
59const JAVASCRIPT_WORKER: &str = r#"
60const readline = require('readline');
61const vm = require('vm');
62const context = vm.createContext({});
63let toolSequence = 0;
64const pendingTools = new Map();
65context.glass = {
66  call: (tool, arguments = {}) => new Promise((resolve, reject) => {
67    const id = `javascript-${++toolSequence}`;
68    pendingTools.set(id, { resolve, reject });
69    process.stdout.write(JSON.stringify({ kind: 'toolCall', id, tool, arguments }) + '\n');
70  }),
71};
72const input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
73input.on('line', async (line) => {
74  let request;
75  try {
76    request = JSON.parse(line);
77    if (request.kind === 'toolResult') {
78      const pending = pendingTools.get(request.id);
79      if (!pending) throw new Error('unknown Glass tool response');
80      pendingTools.delete(request.id);
81      if (request.ok) pending.resolve(request.result);
82      else pending.reject(new Error(request.error || 'Glass tool call failed'));
83      return;
84    }
85    const output = [];
86    context.console = {
87      log: (...values) => output.push(values.map(String).join(' ')),
88      error: (...values) => output.push(values.map(String).join(' ')),
89    };
90    let value = new vm.Script(request.code, { filename: '<glass>' })
91      .runInContext(context, { timeout: request.timeoutMs });
92    if (value && typeof value.then === 'function') value = await value;
93    process.stdout.write(JSON.stringify({ kind: 'executionResult', ok: true, output: output.join('\n') + (output.length ? '\n' : ''), value: value === undefined ? null : String(value) }) + '\n');
94  } catch (error) {
95    process.stdout.write(JSON.stringify({ kind: 'executionResult', ok: false, output: '', error: String(error && error.stack || error) }) + '\n');
96  }
97});
98"#;
99
100pub type KernelResult<T> = Result<T, KernelError>;
101
102#[derive(Debug)]
103pub enum KernelError {
104    Io(std::io::Error),
105    Sql(rusqlite::Error),
106    InvalidInput(String),
107    Unavailable(String),
108    Protocol(String),
109    Execution(String),
110    Timeout(String),
111}
112
113impl fmt::Display for KernelError {
114    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
115        match self {
116            Self::Io(error) => write!(formatter, "kernel I/O error: {error}"),
117            Self::Sql(error) => write!(formatter, "SQL kernel error: {error}"),
118            Self::InvalidInput(message) => write!(formatter, "invalid kernel input: {message}"),
119            Self::Unavailable(message) => write!(formatter, "kernel unavailable: {message}"),
120            Self::Protocol(message) => write!(formatter, "kernel protocol error: {message}"),
121            Self::Execution(message) => write!(formatter, "kernel execution failed: {message}"),
122            Self::Timeout(message) => write!(formatter, "kernel execution timed out: {message}"),
123        }
124    }
125}
126
127impl std::error::Error for KernelError {}
128
129impl From<std::io::Error> for KernelError {
130    fn from(error: std::io::Error) -> Self {
131        Self::Io(error)
132    }
133}
134
135impl From<rusqlite::Error> for KernelError {
136    fn from(error: rusqlite::Error) -> Self {
137        Self::Sql(error)
138    }
139}
140
141#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
142#[serde(rename_all = "camelCase")]
143pub enum KernelKind {
144    Python,
145    JavaScript,
146    Shell,
147    Sql,
148}
149
150#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
151#[serde(rename_all = "camelCase")]
152pub enum KernelState {
153    Ready,
154    Failed,
155    Stopped,
156}
157
158#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
159#[serde(rename_all = "camelCase")]
160pub struct KernelSnapshot {
161    pub name: String,
162    pub kind: KernelKind,
163    pub state: KernelState,
164    pub executions: u64,
165    pub actor_id: String,
166    pub workspace_revision: u64,
167    #[serde(default)]
168    pub capabilities: Vec<String>,
169    #[serde(default)]
170    pub mutation_authority: bool,
171}
172
173#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
174#[serde(rename_all = "camelCase")]
175pub struct KernelExecution {
176    pub name: String,
177    pub kind: KernelKind,
178    pub sequence: u64,
179    pub actor_id: String,
180    pub initiator_id: String,
181    pub executor_id: String,
182    pub workspace_revision: u64,
183    pub duration_ms: u64,
184    pub output: String,
185    pub value: Value,
186    pub truncated: bool,
187    pub tool_calls: u64,
188}
189
190#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
191#[serde(rename_all = "camelCase")]
192pub struct KernelToolCall {
193    pub id: String,
194    pub tool: String,
195    #[serde(default)]
196    pub arguments: Value,
197}
198
199enum KernelBackend {
200    Json(JsonProcessKernel),
201    Shell(ShellKernel),
202    Sql(SqlKernel),
203}
204
205struct KernelSession {
206    snapshot: KernelSnapshot,
207    backend: KernelBackend,
208    capabilities: BTreeSet<String>,
209}
210
211pub struct KernelManager {
212    root: PathBuf,
213    sessions: BTreeMap<String, KernelSession>,
214}
215
216impl KernelManager {
217    pub fn new(root: impl AsRef<Path>) -> KernelResult<Self> {
218        Ok(Self {
219            root: root.as_ref().canonicalize()?,
220            sessions: BTreeMap::new(),
221        })
222    }
223
224    pub fn start(&mut self, name: &str, kind: KernelKind, actor_id: &str) -> KernelResult<()> {
225        self.start_governed(name, kind, actor_id, &[], false)
226    }
227
228    pub fn start_governed(
229        &mut self,
230        name: &str,
231        kind: KernelKind,
232        actor_id: &str,
233        capabilities: &[String],
234        mutation_authority: bool,
235    ) -> KernelResult<()> {
236        validate_name(name, "kernel")?;
237        validate_actor_id(actor_id, "kernel actor")?;
238        let capabilities = validate_capabilities(capabilities)?;
239        if self.sessions.contains_key(name) {
240            return Err(KernelError::InvalidInput(format!(
241                "kernel {name} already exists"
242            )));
243        }
244        if self.sessions.len() == MAX_KERNEL_SESSIONS {
245            return Err(KernelError::InvalidInput(format!(
246                "kernel session limit is {MAX_KERNEL_SESSIONS}"
247            )));
248        }
249        let backend = match kind {
250            KernelKind::Python => KernelBackend::Json(JsonProcessKernel::spawn(
251                &self.root,
252                if cfg!(windows) { "python" } else { "python3" },
253                &["-u", "-c", PYTHON_WORKER],
254            )?),
255            KernelKind::JavaScript => KernelBackend::Json(JsonProcessKernel::spawn(
256                &self.root,
257                "node",
258                &["-e", JAVASCRIPT_WORKER],
259            )?),
260            KernelKind::Shell => KernelBackend::Shell(ShellKernel::spawn(&self.root)?),
261            KernelKind::Sql => KernelBackend::Sql(SqlKernel::new()?),
262        };
263        self.sessions.insert(
264            name.to_string(),
265            KernelSession {
266                snapshot: KernelSnapshot {
267                    name: name.to_string(),
268                    kind,
269                    state: KernelState::Ready,
270                    executions: 0,
271                    actor_id: actor_id.to_string(),
272                    workspace_revision: 0,
273                    capabilities: capabilities.iter().cloned().collect(),
274                    mutation_authority,
275                },
276                backend,
277                capabilities,
278            },
279        );
280        Ok(())
281    }
282
283    pub fn execute(
284        &mut self,
285        name: &str,
286        code: &str,
287        actor_id: &str,
288        workspace_revision: u64,
289        timeout: Option<Duration>,
290    ) -> KernelResult<KernelExecution> {
291        self.execute_with_tools(name, code, actor_id, workspace_revision, timeout, |_| {
292            Err(KernelError::Execution(
293                "kernel has no governed Glass tool dispatcher".into(),
294            ))
295        })
296    }
297
298    pub fn execute_with_tools(
299        &mut self,
300        name: &str,
301        code: &str,
302        initiator_id: &str,
303        workspace_revision: u64,
304        timeout: Option<Duration>,
305        mut dispatch: impl FnMut(&KernelToolCall) -> KernelResult<Value>,
306    ) -> KernelResult<KernelExecution> {
307        validate_code(code)?;
308        validate_actor_id(initiator_id, "kernel initiator")?;
309        let timeout = timeout.unwrap_or(DEFAULT_KERNEL_TIMEOUT);
310        if timeout.is_zero() || timeout > Duration::from_secs(600) {
311            return Err(KernelError::InvalidInput(
312                "kernel timeout must be between 1 ms and 600 seconds".into(),
313            ));
314        }
315        let session = self
316            .sessions
317            .get_mut(name)
318            .ok_or_else(|| KernelError::InvalidInput(format!("unknown kernel {name}")))?;
319        if session.snapshot.state != KernelState::Ready {
320            return Err(KernelError::Execution(format!(
321                "kernel {name} is not ready"
322            )));
323        }
324        let started = Instant::now();
325        let executor_id = format!("kernel:{name}");
326        let capabilities = session.capabilities.clone();
327        let mut tool_calls = 0_u64;
328        let mut governed_dispatch = |call: &KernelToolCall| {
329            validate_name(&call.id, "kernel tool call ID")?;
330            tool_calls = tool_calls.saturating_add(1);
331            if tool_calls > MAX_KERNEL_TOOL_CALLS as u64 {
332                return Err(KernelError::Execution(format!(
333                    "kernel execution exceeded {MAX_KERNEL_TOOL_CALLS} Glass tool calls"
334                )));
335            }
336            if call.tool.starts_with("glass.eval.") {
337                return Err(KernelError::Execution(
338                    "recursive glass.eval tool calls are forbidden".into(),
339                ));
340            }
341            if !capabilities.contains(&call.tool) {
342                return Err(KernelError::Execution(format!(
343                    "kernel capability {} was not granted",
344                    call.tool
345                )));
346            }
347            dispatch(call)
348        };
349        let result = match &mut session.backend {
350            KernelBackend::Json(kernel) => kernel.execute(code, timeout, &mut governed_dispatch),
351            KernelBackend::Shell(kernel) => kernel.execute(code, timeout, &mut governed_dispatch),
352            KernelBackend::Sql(kernel) => kernel.execute(code, &mut governed_dispatch),
353        };
354        let (output, value, truncated) = match result {
355            Ok(result) => result,
356            Err(error) => {
357                if matches!(error, KernelError::Protocol(_) | KernelError::Timeout(_)) {
358                    session.snapshot.state = KernelState::Failed;
359                }
360                return Err(error);
361            }
362        };
363        session.snapshot.executions = session
364            .snapshot
365            .executions
366            .checked_add(1)
367            .ok_or_else(|| KernelError::Protocol("kernel sequence overflowed".into()))?;
368        session.snapshot.actor_id = executor_id.clone();
369        session.snapshot.workspace_revision = workspace_revision;
370        Ok(KernelExecution {
371            name: name.to_string(),
372            kind: session.snapshot.kind,
373            sequence: session.snapshot.executions,
374            actor_id: executor_id.clone(),
375            initiator_id: initiator_id.to_string(),
376            executor_id,
377            workspace_revision,
378            duration_ms: started.elapsed().as_millis() as u64,
379            output,
380            value,
381            truncated,
382            tool_calls,
383        })
384    }
385
386    pub fn snapshots(&self) -> impl Iterator<Item = &KernelSnapshot> {
387        self.sessions.values().map(|session| &session.snapshot)
388    }
389
390    pub fn snapshot(&self, name: &str) -> Option<&KernelSnapshot> {
391        self.sessions.get(name).map(|session| &session.snapshot)
392    }
393
394    pub fn stop(&mut self, name: &str) -> KernelResult<KernelSnapshot> {
395        let mut session = self
396            .sessions
397            .remove(name)
398            .ok_or_else(|| KernelError::InvalidInput(format!("unknown kernel {name}")))?;
399        session.stop();
400        Ok(session.snapshot.clone())
401    }
402
403    pub fn cancel(&mut self, name: &str) -> KernelResult<KernelSnapshot> {
404        let session = self
405            .sessions
406            .get_mut(name)
407            .ok_or_else(|| KernelError::InvalidInput(format!("unknown kernel {name}")))?;
408        session.stop();
409        session.snapshot.state = KernelState::Failed;
410        Ok(session.snapshot.clone())
411    }
412
413    pub fn reset(&mut self, name: &str, actor_id: &str) -> KernelResult<()> {
414        let session = self
415            .sessions
416            .get(name)
417            .ok_or_else(|| KernelError::InvalidInput(format!("unknown kernel {name}")))?;
418        let kind = session.snapshot.kind;
419        let capabilities = session.snapshot.capabilities.clone();
420        let mutation_authority = session.snapshot.mutation_authority;
421        self.stop(name)?;
422        self.start_governed(name, kind, actor_id, &capabilities, mutation_authority)
423    }
424}
425
426impl KernelSession {
427    fn stop(&mut self) {
428        match &mut self.backend {
429            KernelBackend::Json(kernel) => kernel.stop(),
430            KernelBackend::Shell(kernel) => kernel.stop(),
431            KernelBackend::Sql(_) => {}
432        }
433        self.snapshot.state = KernelState::Stopped;
434    }
435}
436
437impl Drop for KernelSession {
438    fn drop(&mut self) {
439        self.stop();
440    }
441}
442
443struct JsonProcessKernel {
444    child: Child,
445    stdin: ChildStdin,
446    responses: Receiver<KernelResult<Value>>,
447    reader: Option<JoinHandle<()>>,
448    stderr_drain: Option<JoinHandle<()>>,
449}
450
451impl JsonProcessKernel {
452    fn spawn(root: &Path, program: &str, arguments: &[&str]) -> KernelResult<Self> {
453        let mut child = Command::new(program)
454            .args(arguments)
455            .current_dir(root)
456            .stdin(Stdio::piped())
457            .stdout(Stdio::piped())
458            .stderr(Stdio::piped())
459            .spawn()
460            .map_err(|error| {
461                if error.kind() == std::io::ErrorKind::NotFound {
462                    KernelError::Unavailable(format!("{program} was not found"))
463                } else {
464                    KernelError::Io(error)
465                }
466            })?;
467        let stdin = child
468            .stdin
469            .take()
470            .ok_or_else(|| KernelError::Protocol("kernel stdin was unavailable".into()))?;
471        let stdout = child
472            .stdout
473            .take()
474            .ok_or_else(|| KernelError::Protocol("kernel stdout was unavailable".into()))?;
475        let stderr = child
476            .stderr
477            .take()
478            .ok_or_else(|| KernelError::Protocol("kernel stderr was unavailable".into()))?;
479        let (sender, responses) = mpsc::sync_channel(MAX_KERNEL_MESSAGES);
480        let reader = std::thread::spawn(move || {
481            for line in BufReader::new(stdout).lines() {
482                let response = line.map_err(KernelError::Io).and_then(|line| {
483                    if line.len() > MAX_KERNEL_OUTPUT_BYTES {
484                        return Err(KernelError::Protocol(
485                            "kernel response exceeded the output limit".into(),
486                        ));
487                    }
488                    serde_json::from_str(&line).map_err(|error| {
489                        KernelError::Protocol(format!("invalid kernel response: {error}"))
490                    })
491                });
492                match sender.try_send(response) {
493                    Ok(()) => {}
494                    Err(TrySendError::Full(_) | TrySendError::Disconnected(_)) => break,
495                }
496            }
497        });
498        let stderr_drain = std::thread::spawn(move || {
499            let mut stderr = stderr;
500            let _ = std::io::copy(&mut stderr, &mut std::io::sink());
501        });
502        Ok(Self {
503            child,
504            stdin,
505            responses,
506            reader: Some(reader),
507            stderr_drain: Some(stderr_drain),
508        })
509    }
510
511    fn execute(
512        &mut self,
513        code: &str,
514        timeout: Duration,
515        dispatch: &mut impl FnMut(&KernelToolCall) -> KernelResult<Value>,
516    ) -> KernelResult<KernelOutput> {
517        serde_json::to_writer(
518            &mut self.stdin,
519            &json!({"code": code, "timeoutMs": timeout.as_millis()}),
520        )
521        .map_err(|error| {
522            KernelError::Protocol(format!("could not encode kernel input: {error}"))
523        })?;
524        self.stdin.write_all(b"\n")?;
525        self.stdin.flush()?;
526        let deadline = Instant::now() + timeout;
527        let response = loop {
528            let remaining = deadline.saturating_duration_since(Instant::now());
529            let response = match self.responses.recv_timeout(remaining) {
530                Ok(response) => response?,
531                Err(RecvTimeoutError::Timeout) => {
532                    self.stop();
533                    return Err(KernelError::Timeout(format!(
534                        "execution exceeded {} ms",
535                        timeout.as_millis()
536                    )));
537                }
538                Err(RecvTimeoutError::Disconnected) => {
539                    return Err(KernelError::Protocol(
540                        "kernel response stream closed".into(),
541                    ));
542                }
543            };
544            if response.get("kind").and_then(Value::as_str) == Some("toolCall") {
545                let call: KernelToolCall = serde_json::from_value(response).map_err(|error| {
546                    KernelError::Protocol(format!("invalid kernel tool call: {error}"))
547                })?;
548                let dispatched = dispatch(&call);
549                let response = match dispatched {
550                    Ok(result) => {
551                        json!({"kind":"toolResult","id":call.id,"ok":true,"result":result})
552                    }
553                    Err(error) => {
554                        json!({"kind":"toolResult","id":call.id,"ok":false,"error":error.to_string()})
555                    }
556                };
557                serde_json::to_writer(&mut self.stdin, &response).map_err(|error| {
558                    KernelError::Protocol(format!("could not encode kernel tool result: {error}"))
559                })?;
560                self.stdin.write_all(b"\n")?;
561                self.stdin.flush()?;
562                continue;
563            }
564            if response.get("kind").and_then(Value::as_str) != Some("executionResult") {
565                return Err(KernelError::Protocol(
566                    "kernel response has an unknown message kind".into(),
567                ));
568            }
569            break response;
570        };
571        if response.get("ok").and_then(Value::as_bool) != Some(true) {
572            return Err(KernelError::Execution(
573                response
574                    .get("error")
575                    .and_then(Value::as_str)
576                    .unwrap_or("kernel returned an unsuccessful response")
577                    .to_string(),
578            ));
579        }
580        bounded_output(
581            response
582                .get("output")
583                .and_then(Value::as_str)
584                .unwrap_or_default(),
585            response.get("value").cloned().unwrap_or(Value::Null),
586        )
587    }
588
589    fn stop(&mut self) {
590        if self.child.try_wait().ok().flatten().is_none() {
591            let _ = self.child.kill();
592            let _ = self.child.wait();
593        }
594        if let Some(reader) = self.reader.take() {
595            let _ = reader.join();
596        }
597        if let Some(stderr_drain) = self.stderr_drain.take() {
598            let _ = stderr_drain.join();
599        }
600    }
601}
602
603struct ShellKernel {
604    child: Child,
605    stdin: ChildStdin,
606    lines: Receiver<KernelResult<String>>,
607    reader: Option<JoinHandle<()>>,
608    sequence: u64,
609    response_dir: PathBuf,
610}
611
612impl ShellKernel {
613    #[cfg(unix)]
614    fn spawn(root: &Path) -> KernelResult<Self> {
615        let response_dir = std::env::temp_dir().join(format!(
616            "glass-shell-kernel-{}-{}",
617            std::process::id(),
618            std::time::SystemTime::now()
619                .duration_since(std::time::UNIX_EPOCH)
620                .map_err(|error| KernelError::Protocol(error.to_string()))?
621                .as_nanos()
622        ));
623        std::fs::create_dir(&response_dir)?;
624        let mut child = Command::new("/bin/sh")
625            .current_dir(root)
626            .env("GLASS_SHELL_RESPONSE_DIR", &response_dir)
627            .stdin(Stdio::piped())
628            .stdout(Stdio::piped())
629            .stderr(Stdio::null())
630            .spawn()?;
631        let mut stdin = child
632            .stdin
633            .take()
634            .ok_or_else(|| KernelError::Protocol("shell stdin was unavailable".into()))?;
635        let stdout = child
636            .stdout
637            .take()
638            .ok_or_else(|| KernelError::Protocol("shell stdout was unavailable".into()))?;
639        stdin.write_all(
640            br#"glass_tool_sequence=0
641glass_call() {
642  glass_tool_sequence=$((glass_tool_sequence + 1))
643  glass_tool_arguments="$2"
644  [ -n "$glass_tool_arguments" ] || glass_tool_arguments='{}'
645  glass_tool_response="$GLASS_SHELL_RESPONSE_DIR/response-$glass_tool_sequence"
646  rm -f "$glass_tool_response"
647  printf '__GLASS_TOOL_CALL__:%s\t%s\t%s\n' "$glass_tool_sequence" "$1" "$glass_tool_arguments"
648  while [ ! -f "$glass_tool_response" ]; do sleep 0.01; done
649  cat "$glass_tool_response"
650  rm -f "$glass_tool_response"
651  printf '\n'
652}
653"#,
654        )?;
655        stdin.flush()?;
656        let (sender, lines) = mpsc::sync_channel(MAX_KERNEL_MESSAGES);
657        let reader = std::thread::spawn(move || {
658            for line in BufReader::new(stdout).lines() {
659                let line = line.map_err(KernelError::Io);
660                match sender.try_send(line) {
661                    Ok(()) => {}
662                    Err(TrySendError::Full(_) | TrySendError::Disconnected(_)) => break,
663                }
664            }
665        });
666        Ok(Self {
667            child,
668            stdin,
669            lines,
670            reader: Some(reader),
671            sequence: 0,
672            response_dir,
673        })
674    }
675
676    #[cfg(windows)]
677    fn spawn(_root: &Path) -> KernelResult<Self> {
678        Err(KernelError::Unavailable(
679            "persistent shell kernels are not yet available on Windows".into(),
680        ))
681    }
682
683    #[cfg(unix)]
684    fn execute(
685        &mut self,
686        code: &str,
687        timeout: Duration,
688        dispatch: &mut impl FnMut(&KernelToolCall) -> KernelResult<Value>,
689    ) -> KernelResult<KernelOutput> {
690        self.sequence = self
691            .sequence
692            .checked_add(1)
693            .ok_or_else(|| KernelError::Protocol("shell sequence overflowed".into()))?;
694        let marker = format!("__GLASS_SHELL_{}__", self.sequence);
695        writeln!(
696            self.stdin,
697            "{{\n{code}\n}} 2>&1\nglass_status=$?\nprintf '{marker}:%s\\n' \"$glass_status\""
698        )?;
699        self.stdin.flush()?;
700        let deadline = Instant::now() + timeout;
701        let mut output = String::new();
702        let mut truncated = false;
703        loop {
704            let remaining = deadline.saturating_duration_since(Instant::now());
705            if remaining.is_zero() {
706                self.stop();
707                return Err(KernelError::Timeout(format!(
708                    "execution exceeded {} ms",
709                    timeout.as_millis()
710                )));
711            }
712            let line = match self.lines.recv_timeout(remaining) {
713                Ok(line) => line?,
714                Err(RecvTimeoutError::Timeout) => {
715                    self.stop();
716                    return Err(KernelError::Timeout(format!(
717                        "execution exceeded {} ms",
718                        timeout.as_millis()
719                    )));
720                }
721                Err(RecvTimeoutError::Disconnected) => {
722                    return Err(KernelError::Protocol("shell output stream closed".into()));
723                }
724            };
725            let marker_prefix = format!("{marker}:");
726            if let Some(marker_index) = line.find(&marker_prefix) {
727                append_bounded(&mut output, &line[..marker_index], &mut truncated);
728                let status = line[marker_index + marker_prefix.len()..].trim();
729                let status = status.parse::<i32>().map_err(|_| {
730                    KernelError::Protocol("shell returned an invalid exit status".into())
731                })?;
732                if status != 0 {
733                    return Err(KernelError::Execution(format!(
734                        "shell command exited with status {status}: {output}"
735                    )));
736                }
737                return Ok((output, json!({"exitCode": status}), truncated));
738            }
739            if let Some(request) = line.strip_prefix("__GLASS_TOOL_CALL__:") {
740                let mut fields = request.splitn(3, '\t');
741                let request_id = fields
742                    .next()
743                    .and_then(|value| value.parse::<u64>().ok())
744                    .filter(|value| *value > 0)
745                    .ok_or_else(|| {
746                        KernelError::Protocol("shell Glass tool call has an invalid ID".into())
747                    })?;
748                let tool = fields.next().ok_or_else(|| {
749                    KernelError::Protocol("shell Glass tool call has no tool".into())
750                })?;
751                let arguments = fields.next().ok_or_else(|| {
752                    KernelError::Protocol("shell Glass tool call has no arguments".into())
753                })?;
754                let call = KernelToolCall {
755                    id: format!("shell-{request_id}"),
756                    tool: tool.to_string(),
757                    arguments: serde_json::from_str(arguments).map_err(|error| {
758                        KernelError::Protocol(format!(
759                            "shell Glass tool arguments are invalid JSON: {error}"
760                        ))
761                    })?,
762                };
763                let result = dispatch(&call)?;
764                let response = serde_json::to_vec(&result).map_err(|error| {
765                    KernelError::Protocol(format!("could not encode shell tool result: {error}"))
766                })?;
767                let response_path = self.response_dir.join(format!("response-{request_id}"));
768                let temporary_path = self.response_dir.join(format!("response-{request_id}.tmp"));
769                std::fs::write(&temporary_path, response)?;
770                std::fs::rename(temporary_path, response_path)?;
771                continue;
772            }
773            append_bounded(&mut output, &line, &mut truncated);
774            append_bounded(&mut output, "\n", &mut truncated);
775        }
776    }
777
778    #[cfg(windows)]
779    fn execute(
780        &mut self,
781        _code: &str,
782        _timeout: Duration,
783        _dispatch: &mut impl FnMut(&KernelToolCall) -> KernelResult<Value>,
784    ) -> KernelResult<KernelOutput> {
785        Err(KernelError::Unavailable(
786            "persistent shell kernels are not yet available on Windows".into(),
787        ))
788    }
789
790    fn stop(&mut self) {
791        if self.child.try_wait().ok().flatten().is_none() {
792            let _ = self.child.kill();
793            let _ = self.child.wait();
794        }
795        if let Some(reader) = self.reader.take() {
796            let _ = reader.join();
797        }
798        let _ = std::fs::remove_dir_all(&self.response_dir);
799    }
800}
801
802struct SqlKernel {
803    connection: rusqlite::Connection,
804}
805
806impl SqlKernel {
807    fn new() -> KernelResult<Self> {
808        Ok(Self {
809            connection: rusqlite::Connection::open_in_memory()?,
810        })
811    }
812
813    fn execute(
814        &mut self,
815        code: &str,
816        dispatch: &mut impl FnMut(&KernelToolCall) -> KernelResult<Value>,
817    ) -> KernelResult<KernelOutput> {
818        if let Some(request) = code.trim().strip_prefix("GLASS CALL ") {
819            let call: KernelToolCall = serde_json::from_str(request).map_err(|error| {
820                KernelError::InvalidInput(format!("invalid SQL Glass tool call: {error}"))
821            })?;
822            return bounded_output("", dispatch(&call)?);
823        }
824        let leading = code.trim_start().to_ascii_uppercase();
825        if !["SELECT", "WITH", "PRAGMA", "EXPLAIN"]
826            .iter()
827            .any(|keyword| leading.starts_with(keyword))
828        {
829            self.connection.execute_batch(code)?;
830            return Ok((String::new(), Value::Null, false));
831        }
832        let mut statement = self.connection.prepare(code)?;
833        if statement.column_count() == 0 {
834            drop(statement);
835            self.connection.execute_batch(code)?;
836            return Ok((String::new(), Value::Null, false));
837        }
838        let names = statement
839            .column_names()
840            .into_iter()
841            .map(str::to_string)
842            .collect::<Vec<_>>();
843        let column_count = names.len();
844        let rows = statement.query_map([], |row| {
845            let mut record = serde_json::Map::new();
846            for (index, name) in names.iter().enumerate().take(column_count) {
847                record.insert(name.clone(), sql_value(row.get_ref(index)?));
848            }
849            Ok(Value::Object(record))
850        })?;
851        let mut values = Vec::new();
852        for row in rows.take(100_000) {
853            values.push(row?);
854            if serde_json::to_vec(&values)
855                .map_err(|error| KernelError::Protocol(error.to_string()))?
856                .len()
857                > MAX_KERNEL_OUTPUT_BYTES
858            {
859                values.pop();
860                return Ok((String::new(), Value::Array(values), true));
861            }
862        }
863        Ok((String::new(), Value::Array(values), false))
864    }
865}
866
867type KernelOutput = (String, Value, bool);
868
869fn sql_value(value: ValueRef<'_>) -> Value {
870    match value {
871        ValueRef::Null => Value::Null,
872        ValueRef::Integer(value) => json!(value),
873        ValueRef::Real(value) => json!(value),
874        ValueRef::Text(value) => String::from_utf8_lossy(value).into_owned().into(),
875        ValueRef::Blob(value) => json!({"blobBytes": value.len()}),
876    }
877}
878
879fn bounded_output(output: &str, value: Value) -> KernelResult<KernelOutput> {
880    let mut retained = String::new();
881    let mut truncated = false;
882    append_bounded(&mut retained, output, &mut truncated);
883    let encoded_value = serde_json::to_vec(&value).map_err(|error| {
884        KernelError::Protocol(format!("could not encode kernel value: {error}"))
885    })?;
886    if encoded_value.len() > MAX_KERNEL_OUTPUT_BYTES {
887        return Ok((retained, Value::Null, true));
888    }
889    Ok((retained, value, truncated))
890}
891
892fn append_bounded(output: &mut String, value: &str, truncated: &mut bool) {
893    let remaining = MAX_KERNEL_OUTPUT_BYTES.saturating_sub(output.len());
894    if value.len() <= remaining {
895        output.push_str(value);
896    } else {
897        let boundary = value
898            .char_indices()
899            .take_while(|(index, _)| *index <= remaining)
900            .map(|(index, _)| index)
901            .last()
902            .unwrap_or(0);
903        output.push_str(&value[..boundary]);
904        *truncated = true;
905    }
906}
907
908fn validate_code(code: &str) -> KernelResult<()> {
909    if code.is_empty() || code.len() > MAX_KERNEL_CODE_BYTES {
910        return Err(KernelError::InvalidInput(format!(
911            "kernel code must contain 1..={MAX_KERNEL_CODE_BYTES} bytes"
912        )));
913    }
914    Ok(())
915}
916
917fn validate_capabilities(capabilities: &[String]) -> KernelResult<BTreeSet<String>> {
918    if capabilities.len() > 64 {
919        return Err(KernelError::InvalidInput(
920            "kernel capability limit is 64".into(),
921        ));
922    }
923    capabilities
924        .iter()
925        .map(|capability| {
926            if capability.is_empty()
927                || capability.len() > 128
928                || capability.starts_with("glass.eval.")
929                || !capability
930                    .chars()
931                    .all(|character| character.is_ascii_alphanumeric() || ".-_".contains(character))
932            {
933                return Err(KernelError::InvalidInput(format!(
934                    "invalid or recursive kernel capability {capability}"
935                )));
936            }
937            Ok(capability.clone())
938        })
939        .collect()
940}
941
942fn validate_name(name: &str, description: &str) -> KernelResult<()> {
943    if name.is_empty()
944        || name.len() > 128
945        || !name
946            .chars()
947            .all(|character| character.is_ascii_alphanumeric() || "-_.".contains(character))
948    {
949        return Err(KernelError::InvalidInput(format!(
950            "{description} must be 1..=128 ASCII letters, digits, '-', '_' or '.'"
951        )));
952    }
953    Ok(())
954}
955
956fn validate_actor_id(name: &str, description: &str) -> KernelResult<()> {
957    if name.is_empty()
958        || name.len() > 128
959        || !name
960            .chars()
961            .all(|character| character.is_ascii_alphanumeric() || "-_.:".contains(character))
962    {
963        return Err(KernelError::InvalidInput(format!(
964            "{description} must be 1..=128 ASCII letters, digits, '-', '_', '.' or ':'"
965        )));
966    }
967    Ok(())
968}
969
970#[cfg(test)]
971mod tests {
972    use super::*;
973    use std::sync::atomic::{AtomicU64, Ordering};
974
975    static NEXT_ROOT: AtomicU64 = AtomicU64::new(0);
976
977    fn root() -> PathBuf {
978        let sequence = NEXT_ROOT.fetch_add(1, Ordering::Relaxed);
979        let root = std::env::temp_dir().join(format!(
980            "glass-kernel-manager-{}-{sequence}",
981            std::process::id()
982        ));
983        std::fs::create_dir_all(&root).unwrap();
984        root
985    }
986
987    #[test]
988    fn python_kernel_preserves_state_and_attribution() {
989        let root = root();
990        let mut kernels = KernelManager::new(&root).unwrap();
991        kernels
992            .start("python", KernelKind::Python, "human")
993            .unwrap();
994        kernels
995            .execute("python", "answer = 40", "human", 1, None)
996            .unwrap();
997        let result = kernels
998            .execute("python", "answer + 2", "agent", 2, None)
999            .unwrap();
1000        assert_eq!(result.value, "42");
1001        assert_eq!(result.actor_id, "kernel:python");
1002        assert_eq!(result.initiator_id, "agent");
1003        assert_eq!(result.executor_id, "kernel:python");
1004        assert_eq!(result.workspace_revision, 2);
1005        assert_eq!(kernels.snapshot("python").unwrap().executions, 2);
1006        kernels.stop("python").unwrap();
1007        std::fs::remove_dir_all(root).unwrap();
1008    }
1009
1010    #[cfg(unix)]
1011    #[test]
1012    fn shell_kernel_preserves_environment_and_directory_state() {
1013        let root = root();
1014        let mut kernels = KernelManager::new(&root).unwrap();
1015        kernels.start("shell", KernelKind::Shell, "human").unwrap();
1016        kernels
1017            .execute("shell", "value=glass", "human", 1, None)
1018            .unwrap();
1019        let result = kernels
1020            .execute("shell", "printf '%s' \"$value\"", "human", 1, None)
1021            .unwrap();
1022        assert_eq!(result.output, "glass");
1023        kernels.stop("shell").unwrap();
1024        std::fs::remove_dir_all(root).unwrap();
1025    }
1026
1027    #[test]
1028    fn sql_kernel_preserves_tables_and_returns_structured_rows() {
1029        let root = root();
1030        let mut kernels = KernelManager::new(&root).unwrap();
1031        kernels.start("sql", KernelKind::Sql, "agent").unwrap();
1032        kernels
1033            .execute(
1034                "sql",
1035                "CREATE TABLE inventory (sku TEXT, count INTEGER); INSERT INTO inventory VALUES ('x', 0);",
1036                "agent",
1037                1,
1038                None,
1039            )
1040            .unwrap();
1041        let result = kernels
1042            .execute("sql", "SELECT sku, count FROM inventory", "agent", 1, None)
1043            .unwrap();
1044        assert_eq!(result.value[0]["sku"], "x");
1045        assert_eq!(result.value[0]["count"], 0);
1046        drop(kernels);
1047        std::fs::remove_dir_all(root).unwrap();
1048    }
1049
1050    #[test]
1051    fn kernel_names_code_and_timeouts_fail_closed() {
1052        assert!(validate_name("python-1", "kernel").is_ok());
1053        assert!(validate_name("../escape", "kernel").is_err());
1054        assert!(validate_code("").is_err());
1055        assert!(validate_code(&"x".repeat(MAX_KERNEL_CODE_BYTES + 1)).is_err());
1056    }
1057
1058    #[test]
1059    fn python_and_javascript_bindings_dispatch_granted_capabilities() {
1060        let root = root();
1061        let capability = vec!["glass.test.results".to_string()];
1062        for (name, kind, code) in [
1063            (
1064                "python-binding",
1065                KernelKind::Python,
1066                "glass.call('glass.test.results', {'limit': 1})",
1067            ),
1068            (
1069                "javascript-binding",
1070                KernelKind::JavaScript,
1071                "glass.call('glass.test.results', {limit: 1}).then(value => value.count)",
1072            ),
1073        ] {
1074            let mut kernels = KernelManager::new(&root).unwrap();
1075            if let Err(error) =
1076                kernels.start_governed(name, kind, &format!("kernel:{name}"), &capability, false)
1077            {
1078                if matches!(error, KernelError::Unavailable(_)) {
1079                    continue;
1080                }
1081                panic!("could not start {name}: {error}");
1082            }
1083            let mut observed = Vec::new();
1084            let execution = kernels
1085                .execute_with_tools(name, code, "agent-0003", 7, None, |call| {
1086                    observed.push(call.clone());
1087                    Ok(json!({"count": 3}))
1088                })
1089                .unwrap();
1090            assert_eq!(execution.initiator_id, "agent-0003");
1091            assert_eq!(execution.executor_id, format!("kernel:{name}"));
1092            assert_eq!(execution.tool_calls, 1);
1093            assert_eq!(observed[0].tool, "glass.test.results");
1094            assert_eq!(observed[0].arguments["limit"], 1);
1095        }
1096        std::fs::remove_dir_all(root).unwrap();
1097    }
1098
1099    #[test]
1100    fn sql_and_shell_bindings_use_the_same_bounded_dispatch_contract() {
1101        let root = root();
1102        let capability = vec!["glass.graph.path".to_string()];
1103        let mut kinds = vec![(
1104            "sql-binding",
1105            KernelKind::Sql,
1106            r#"GLASS CALL {"id":"sql-1","tool":"glass.graph.path","arguments":{"from":"a","to":"b"}}"#,
1107        )];
1108        if cfg!(unix) {
1109            kinds.push((
1110                "shell-binding",
1111                KernelKind::Shell,
1112                r#"glass_call glass.graph.path '{"from":"a","to":"b"}'"#,
1113            ));
1114        }
1115        for (name, kind, code) in kinds {
1116            let mut kernels = KernelManager::new(&root).unwrap();
1117            kernels
1118                .start_governed(name, kind, &format!("kernel:{name}"), &capability, false)
1119                .unwrap();
1120            let result = kernels
1121                .execute_with_tools(name, code, "human:local", 9, None, |call| {
1122                    assert_eq!(call.tool, "glass.graph.path");
1123                    Ok(json!({"path":["a","b"]}))
1124                })
1125                .unwrap();
1126            assert_eq!(result.tool_calls, 1);
1127        }
1128        std::fs::remove_dir_all(root).unwrap();
1129    }
1130
1131    #[test]
1132    fn ungranted_and_recursive_kernel_capabilities_fail_closed() {
1133        assert!(validate_capabilities(&["glass.eval.execute".into()]).is_err());
1134        let root = root();
1135        let mut kernels = KernelManager::new(&root).unwrap();
1136        kernels
1137            .start_governed(
1138                "python-denied",
1139                KernelKind::Python,
1140                "kernel:python-denied",
1141                &["glass.test.results".into()],
1142                false,
1143            )
1144            .unwrap();
1145        let error = kernels
1146            .execute_with_tools(
1147                "python-denied",
1148                "glass.call('glass.file.write', {'path':'x'})",
1149                "agent-0003",
1150                1,
1151                None,
1152                |_| panic!("ungranted call reached the dispatcher"),
1153            )
1154            .unwrap_err();
1155        assert!(error.to_string().contains("not granted"));
1156        drop(kernels);
1157        std::fs::remove_dir_all(root).unwrap();
1158    }
1159}