@ai-ecoverse/slicc-kernel 1.178.4 → 1.179.0

package/README.md

@@ -57,6 +57,7 @@ Runs `argv[0]` with `argv` as its arguments and resolves when it exits. `stdout`
 | option | |
 | --- | --- |
 | `cwd` | working directory, default `/`; created in OPFS if missing. Under `users: 'enforce'`, a `cwd` the user can't search rejects with `code: 'EACCES'` (`cannot change to <cwd>: Permission denied`) and starts nothing, as a `chdir` there fails on Linux; `openTerminal` does the same. A program's spawn with its own `cwd` (`ctx.spawn`, `ctx.sync.run`, a WASIX `posix_spawn` chdir action) is checked the same way and fails with `EACCES`, while a child that inherits its parent's cwd keeps it unchecked, as on Linux |
+| `cwdMissing` | `'create'` (the default) or `'error'`: what happens when `cwd` doesn't exist. `'create'` creates it, with its parents, as described for `cwd`. `'error'` rejects with `code: 'ENOENT'` (`cannot change to <cwd>: No such file or directory`) and starts nothing, as a `chdir` there fails on Linux. A caller that keeps directories in a list to run commands in, and so may name one that was removed since, should pass `'error'`: with `'create'`, its next command brings the removed directory back, empty ([#1808](https://github.com/ai-ecoverse/slicc-kernel/issues/1808)). Any other value rejects with a `TypeError`; `openTerminal` takes it too |
 | `user` | the user to run as, by name or uid (see [Users](#users)); default `root`. An unknown user rejects with `code: 'ENOENT'` |
 | `tag` | a string the kernel keeps with the process and every process it starts (fork, spawn and exec), and hands to `approve` with a [`sudo`](#sudo) request, so the embedder knows which agent asks; nothing a program does changes it. Anything but a string rejects with a `TypeError` |
 | `env` | extra environment, over the user's defaults: `HOME`, `USER`, `LOGNAME`, `PNPM_HOME` and `PATH=$PNPM_HOME/bin:/usr/local/bin:/usr/bin:/bin` (see [Users](#users)), `TZ=<system time zone>` (see [Time zone](#time-zone)), and `PWD=<cwd>` |
@@ -69,7 +70,7 @@ Starts `argv` as the session leader on a new terminal and resolves once it is ru
 
 | option | |
 | --- | --- |
-| `cwd`, `user`, `tag`, `env` | as for `run`; `TERM=xterm-256color` and `COLORTERM=truecolor` are added |
+| `cwd`, `cwdMissing`, `user`, `tag`, `env` | as for `run`; `TERM=xterm-256color` and `COLORTERM=truecolor` are added |
 | `cols`, `rows` | initial size, default 80 × 24, so `$COLUMNS` and `$LINES` are right before the first prompt |
 | `onData` | called with each chunk of output as raw bytes (escape sequences included) |
 
@@ -176,7 +177,7 @@ Attaches to a kernel over a port from `kernel.connect()`, in any realm: a worker
 
 | Client | |
 |---|---|
-| `spawn(argv, { cwd, user, env, stdin, pgid, onStdout, onStderr })` | runs over pipes and resolves with `{ pid, pgid, exited, ended, signal(name) }` once the process has started; `ended` resolves with `{ status, signal }`, `signal` named only when a signal ended the process, as for `kernel.run` (an older kernel never names one); output arrives in chunks, as bytes, and the kernel keeps no copy; every spawn leads its own process group, which `signal` (default `SIGTERM`) signals, unless `pgid` names an existing group to join (protocol 1.3): the process then joins that group and that group's session, as `setpgid` would (a client has no session of its own: each of its spawns and terminals leads one, and `setpgid` cannot cross sessions), and `signal` signals the whole group. The group must have been started by this client (a spawn or a terminal it opened), even if its leader has exited; an unknown group rejects with `code: 'ESRCH'`, another session's with `code: 'EPERM'`, and against a 1.2 kernel the client rejects with `code: 'ENOSYS'` before sending anything, as an older kernel would ignore the option; a program that cannot start rejects with `code: 'ENOENT'`. `user` runs it as another user, which only a root client may (see `kernel.connect`); against a 1.7 kernel the client rejects with `code: 'ENOSYS'` |
+| `spawn(argv, { cwd, cwdMissing, user, env, stdin, pgid, onStdout, onStderr })` | runs over pipes and resolves with `{ pid, pgid, exited, ended, signal(name) }` once the process has started; `ended` resolves with `{ status, signal }`, `signal` named only when a signal ended the process, as for `kernel.run` (an older kernel never names one); output arrives in chunks, as bytes, and the kernel keeps no copy; every spawn leads its own process group, which `signal` (default `SIGTERM`) signals, unless `pgid` names an existing group to join (protocol 1.3): the process then joins that group and that group's session, as `setpgid` would (a client has no session of its own: each of its spawns and terminals leads one, and `setpgid` cannot cross sessions), and `signal` signals the whole group. The group must have been started by this client (a spawn or a terminal it opened), even if its leader has exited; an unknown group rejects with `code: 'ESRCH'`, another session's with `code: 'EPERM'`, and against a 1.2 kernel the client rejects with `code: 'ENOSYS'` before sending anything, as an older kernel would ignore the option; a program that cannot start rejects with `code: 'ENOENT'`. `user` runs it as another user, which only a root client may (see `kernel.connect`); against a 1.7 kernel the client rejects with `code: 'ENOSYS'`. `cwdMissing` is as for `kernel.run` (protocol 1.14); `run` and `openTerminal` take it too, and with `'error'` against a 1.13 kernel, which would create the directory, the client rejects with `code: 'ENOSYS'` before sending anything |
 | `run(argv, options?)` | `spawn` and wait: `{ pid, status, signal, stdout, stderr }` as text, with `onStdout`/`onStderr` streaming text; `signal` as for `kernel.run` |
 | `openTerminal(argv, options?)` | a pty session, as `kernel.openTerminal`, `ended` included |
 | `ps()` | the kernel's processes: `{ pid, ppid, pgid, sid, argv, tty, started, state, rss, utime, stime, uid, gid }`, `state` being `'S'`, `'T'` (stopped) or `'Z'`, `rss` the process's resident memory in bytes (the size of its wasm memory, what `/proc/<pid>/status` shows as `VmRSS`; absent from kernels before 1.61), `utime`/`stime` the CPU time it has used, in milliseconds, in its program and in the kernel's calls (see [`/proc`](#proc); absent for a JS program and from kernels before 1.63) and `uid`/`gid` the effective ids (absent from a 1.7 kernel), and `tag` the process's tag (see `kernel.run`), when it has one, with `tags`, all of them in order, when a spawn added one (see `kernel.connect`), on rows the client's user may see as root or as the same uid. A client bound to a user sees only that user's processes |

package/dist/driver-worker.js

@@ -824,7 +824,7 @@ async function loopbackFetch(dial, input, options) {
 }
 
 // src/client/protocol.ts
-var PROTOCOL = [1, 13];
+var PROTOCOL = [1, 14];
 function locksOf(scope = globalThis) {
   const locks = scope.navigator?.locks;
   return typeof locks?.request === "function" ? locks : void 0;
@@ -1059,6 +1059,8 @@ async function spawnOn(channel, argv, opts) {
   });
   if (opts.tag !== void 0) await since(channel, 12, "a tag per spawn", async () => {
   });
+  if (opts.cwdMissing === "error") await since(channel, 14, "cwdMissing: 'error'", async () => {
+  });
   const started = Promise.withResolvers();
   let endedBy;
   const options = { ...rest, ...stdin !== void 0 ? { stdin: bytesOf2(stdin) } : {} };
@@ -1118,6 +1120,8 @@ async function terminalOn(channel, argv, opts) {
   });
   if (opts.tag !== void 0) await since(channel, 12, "a tag per terminal", async () => {
   });
+  if (opts.cwdMissing === "error") await since(channel, 14, "cwdMissing: 'error'", async () => {
+  });
   let listener = onData ?? null;
   const backlog = [];
   const started = Promise.withResolvers();