@ai-ecoverse/slicc 1.52.0 → 1.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +14 -8
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -169,7 +169,7 @@ Six's `--version`, `version`, `--profile` and `--mount` are seven flags too, and
169
169
  **Restarts.** slicc-node kept its key and port, so an open page reconnected after a restart. `slicc` sets the link up again instead:
170
170
  - A browser that `slicc` launched runs in its own process group. It outlives a `slicc` that crashes or is killed.
171
171
  - The next `slicc` finds that browser's seven tab and links it again, with `attached` and no `launched`. It finds the tab through the profile's `DevToolsActivePort`, or through `--cdp`. Given the same `--mount` and `--kernel-port`, the folders and kernel services come back too.
172
- - Quitting `slicc` normally (`q`, Ctrl-C, `SIGTERM`) closes the browsers that run launched.
172
+ - Quitting `slicc` normally (`q`, Ctrl-C, `SIGTERM`, or the control socket's `stop`) closes the browsers that run launched. The control socket's `detach`, or `SIGTERM` with `--keep-browsers`, leaves them running, for the next run to link again (see [Running links](#running-links-slicc-tray)).
173
173
  - Every new `slicc` process has a new `node` id, so seven sees a new link from the same machine.
174
174
  - `attach` sets up again on every new seven context, and `follow` reconnects by itself, with the same device certificate.
175
175
  - `slicc open` and `slicc pair` keep their certificate and port, so a paired page signals again after a restart, without a new pairing.
@@ -344,7 +344,7 @@ slicc capabilities [--json]
344
344
  - **`agent`:** `events`, the `t` of every agent event slicc knows, and `own`, the lines slicc itself adds to that stream (`settled`, see [Remote control](#remote-control-slicc-prompt-watch-wait-and-abort)).
345
345
  - **`control`:** `v`, the version of the [control socket](#running-links-slicc-tray) protocol, and `ops`, the ops it answers.
346
346
 
347
- A program reads `contract` and the names it needs, and treats anything it doesn't know as absent: an older `slicc` lacks the newer commands, events and ops, and a newer one may have more. `TestCapabilitiesNameEveryCommandEventAndOp` fails when a command, an event or a control op is added to the code without appearing here, and keeps the document's fixture, [`test/integration/testdata/native/capabilities.json`](test/integration/testdata/native/capabilities.json), in step with the binary.
347
+ A program reads `contract` and the names it needs, and treats anything it doesn't know as absent: an older `slicc` lacks the newer commands, events and ops, and a newer one may have more. `TestCapabilitiesNameEveryCommandEventAndOp` fails when a command, an event or a control op is added to the code without appearing here, and keeps the document's fixture, [`test/integration/testdata/native/capabilities.json`](test/integration/testdata/native/capabilities.json), in step with the binary. The control socket's exchange, `status`'s `ops`, the answers to `stop` and `detach` and the `closed` that follows, is in [`control.ndjson`](test/integration/testdata/native/control.ndjson).
348
348
 
349
349
  ### Lifecycle events: `--json` on `attach`, `open`, `pair` and `follow`
350
350
 
@@ -363,7 +363,7 @@ With `--json`, `attach`, `open`, `pair` (and `--default-browser`, which is `open
363
363
  - `link-lost`: `mode`, `reason?` when slicc or seven closed the link (`slicc is exiting`, seven's `bye` reason, `unlinked by <name>` with `code` `UNLINKED` on `follow`), or `message?` for a failure; `device?` on `open` and `pair`.
364
364
  - `reconnecting`: `attempt`, `retryAt` (RFC 3339, UTC), `wait` (milliseconds), `reason?` and `code?` (the failure that led here, and the hub's code), on `follow` before each new dial. These are the `attempt`, `retryAt` and `code` of [`slicc tray --json`](#running-links-slicc-tray).
365
365
  - `error`: `message`, `code?` (the hub's or seven's code, on `follow`), `mode?`, and `retryable`: `true` when slicc goes on by itself (`follow` reconnects, and an offer from seven that slicc can't answer leaves the run waiting for the next one), `false` when the run ends, with exit 1 (exit 2 for a bad `--origin` on `attach`).
366
- - `closed`: `browsers: []`, the last event of every run, also one that failed or was interrupted.
366
+ - `closed`: `browsers: []`, the last event of every run, also one that failed or was interrupted, and `kept: []` after the control socket's `detach`.
367
367
 
368
368
  Secrets stay out: no join URL, no tray token, and no `--cdp` path, since `resources` names browsers by id and errors are redacted as on stderr. Fixtures: [`attach.ndjson`](test/integration/testdata/native/attach.ndjson), [`pair.ndjson`](test/integration/testdata/native/pair.ndjson), [`follow.ndjson`](test/integration/testdata/native/follow.ndjson) and [`follow-error.ndjson`](test/integration/testdata/native/follow-error.ndjson), with values that change from run to run shown as `<…>`.
369
369
 
@@ -382,11 +382,11 @@ Secrets stay out: no join URL, no tray token, and no `--cdp` path, since `resour
382
382
  ```
383
383
  slicc [--browser <id>]... [--cdp <url>]... [--page <url>] [--origin <origin>]... [--profile <name> | --profile six[:<port>]] [--headless]
384
384
  [--name <name>] [--kernel-port <n>] [--no-kernel] [--allow <rule>]... [--deny <rule>]... [--expose-debug-port <port>]... [--mount <path>[:<name>][:ro]]...
385
- [--yes] [--plain] [--json] [--no-fallback] [--open] [--default-browser]
385
+ [--yes] [--plain] [--json] [--no-fallback] [--open] [--default-browser] [--keep-browsers]
386
386
  [--runner <argv…> [--]] [--shell <argv…> [--]] [--eval <argv…> [--]] [--eval-quiet <dur>] [--sftp | --no-sftp]
387
387
  ```
388
388
 
389
- `slicc` with no command (`npx sliccy`) finds browsers, launches or attaches to the best one, opens seven in it and links it. It serves the link until it is told to stop: `q` or Ctrl-C in the dashboard, or `SIGINT` or `SIGTERM`. Then it says `bye` to seven, closes the browsers this run launched (as `slicc launch` does), leaves the browsers it attached to running, and exits 0. If the browser that hosts seven goes away, `slicc` closes the rest and exits 0 too. Setup failures (no browser, a launch or attach that fails) exit 1, and bad flags exit 2. With `--no-fallback`, a run where nothing can host seven says ``no browser to control: run `slicc open` to link seven in your everyday browser`` and exits 1.
389
+ `slicc` with no command (`npx sliccy`) finds browsers, launches or attaches to the best one, opens seven in it and links it. It serves the link until it is told to stop: `q` or Ctrl-C in the dashboard, or `SIGINT` or `SIGTERM`, or the control socket's `stop`. Then it says `bye` to seven, closes the browsers this run launched (as `slicc launch` does), leaves the browsers it attached to running, and exits 0. The control socket's `detach` (or `SIGTERM` with `--keep-browsers`) leaves the launched browsers running too (see [Running links](#running-links-slicc-tray)). If the browser that hosts seven goes away, `slicc` closes the rest and exits 0 too. Setup failures (no browser, a launch or attach that fails) exit 1, and bad flags exit 2. With `--no-fallback`, a run where nothing can host seven says ``no browser to control: run `slicc open` to link seven in your everyday browser`` and exits 1.
390
390
 
391
391
  **The fallback to your default browser.** Plain `slicc` with no SLICC profile and no CDP endpoint falls back to [linking seven in your everyday browser](#linking-seven-in-your-everyday-browser), as `slicc pair` does. On a terminal it doesn't fall back by itself: the picker comes up, with the `Default browser` row first and the best match (see *The picker* below).
392
392
  - **When:** stdin or stdout isn't a terminal, or `--yes`, `--plain` or `--json` was given; no `--browser`, `--cdp` or `--profile` was given and `--no-fallback` wasn't; and discovery found no running CDP endpoint (SLICC six's running Chrome counts too) and no installed Chromium browser with a profile in the SLICC profiles dir. A profile or endpoint, found or given, always wins, so the flow above runs instead. Since slicc never picks six's Chrome by itself, a run whose only endpoint is six's launches an installed browser in a new SLICC profile, or exits 1 with `no browser to control` when there is none.
@@ -420,6 +420,7 @@ The cdp list follows the browsers: an extra that stops answering is taken off th
420
420
  - `--profile <name>`: the SLICC profile for a launched browser that hosts seven. `--profile six` and `--profile six:<port>` use SLICC six's own Chrome profile instead, without the picker (see [Using SLICC six's Chrome profile](#using-slicc-sixs-chrome-profile)).
421
421
  - `--headless`: launch browsers without a window.
422
422
  - `--yes`, `--plain`: no picker. `--json`: NDJSON events, below.
423
+ - `--keep-browsers`: on `SIGTERM`, detach instead of stopping: say `bye` and leave the browsers this run launched running, as the [control socket](#running-links-slicc-tray)'s `detach` does. `SIGINT` and Ctrl-C still close them. Plain mode then ends with `slicc: detached; left <ids> running`. It needs `--plain`, `--yes` or `--json` (or no terminal): where the picker and dashboard would come up, `slicc --keep-browsers` says `--keep-browsers needs --plain, --yes or --json: the dashboard closes the browsers it launched when it quits` and exits 2, since the dashboard takes `SIGTERM` itself.
423
424
  - `--no-fallback`: never fall back to the default browser. slicc then behaves as it did before the fallback: it launches an installed browser in a new SLICC profile, or exits 1 with `no browser to control` when nothing can host seven (see above). `--open`: when falling back without a terminal, open the pairing URL in the default browser too.
424
425
  - `--default-browser`: don't look for browsers; link a seven in the default browser instead, exactly as `slicc open` does (see [Linking seven in your everyday browser](#linking-seven-in-your-everyday-browser)).
425
426
  - A flag of SLICC six's points back to six and exits 2 (see [Coming from SLICC six](#coming-from-slicc-six)). Any other flag, or an argument, is an error.
@@ -453,7 +454,7 @@ The cdp list follows the browsers: an extra that stops answering is taken off th
453
454
  - `link-lost`: `reason?` when slicc or seven closed the link (`slicc is exiting`, `slicc is relinking`, seven's `bye` reason, `replaced by a new offer`), or `message?` for a failure. seven sets the link up again after a reload, and a new `linked` follows.
454
455
  - `browser-gone`, `browser-back`: `browser`, `name`, `role`. A browser stopped answering and left the cdp list, or answers again and is back on it. A `browser-gone` with `reason` `no-browser-session` is for an extra that was never listed, because it has no browser session.
455
456
  - `browser-slow`: `browser`, `name`, `role`, `elapsed` (seconds). A browser slicc launched hasn't written its `DevToolsActivePort` yet, every 10 s from 10 s on (see [`slicc launch`](#slicc-launch---browser-id---profile-name---url-url---headless---no-seven-flags---json)). The dashboard and plain mode show it as `<name> is still starting (slow disk?), <n> s so far`.
456
- - `closed`: `browsers`, the ids slicc closed (always a list). It is the last event of every run that got past choosing its browsers.
457
+ - `closed`: `browsers`, the ids slicc closed (always a list), and `kept` after a detach (the control socket's `detach`, or `SIGTERM` with `--keep-browsers`): the ids of the browsers this run launched and left running, with `browsers` `[]`. It is the last event of every run that got past choosing its browsers.
457
458
  - `error`: `message`, and `browser?` when closing that browser failed. A setup error ends the run with exit 1.
458
459
  - `mode`: `mode` (`loopback`) and `reason` (`no-browser`), when the run [falls back](#the-default-slicc) to the default browser. Then come `pairing`, `linked` and `link-lost` events (each `linked` and `link-lost` with `mode` and `device`, the page's fingerprint), and `closed` with `browsers: []`.
459
460
  - `pairing`: `url`, a pairing URL, after `mode`.
@@ -1373,7 +1374,7 @@ PID MODE SEVEN DEVICE STATE OFFERS
1373
1374
  - **`DEVICE`:** this machine's device, as `follow` and seven's tray see it: for `follow`, the DTLS certificate for that hub, and for `open` and `pair`, the loopback identity. It is the SHA-256 fingerprint, shown as its first and last four hex digits, so a row here matches a row in the leader's `slicc tray`. Over CDP there is none (`-`).
1374
1375
  - **`STATE`:** `waiting` (a local mode, until seven links), `dialing`, `waiting for offer`, `connecting`, `connected` with how long, `reconnecting (#<attempt>, <next wait>)`, or `stopped (<code>)` with the hub's or seven's code (`TRAY_EXPIRED`, `UNLINKED`, …) as the process exits.
1375
1376
  - **`OFFERS`:** `exit` (the network, `--exit` for `follow`), `ssh`, `cdp`, `jerk`, `fs:<name>` per folder, and `kernel:<port>`.
1376
- - **`--json`:** a JSON array, one object per process: `{ "v": 1, "pid", "mode", "version", "started", "seven"?, "origin"?, "hub"?, "device"?, "state", "since", "attempt"?, "retryAt"?, "code"?, "error"?, "offers", "dials", "links", "lastLinked"? }`. `hub` is the hub's origin, `error` the last failure with secrets redacted, `dials` the dials so far and `links` the links that came up. These are SLICC six's follower counters.
1377
+ - **`--json`:** a JSON array, one object per process: `{ "v": 1, "pid", "mode", "version", "started", "seven"?, "origin"?, "hub"?, "device"?, "state", "since", "attempt"?, "retryAt"?, "code"?, "error"?, "offers", "dials", "links", "lastLinked"?, "ops"? }`. `ops` lists the control ops the process answers (see *Control sockets* below); it is missing from a process older than that field. `hub` is the hub's origin, `error` the last failure with secrets redacted, `dials` the dials so far and `links` the links that came up. These are SLICC six's follower counters.
1377
1378
  - **`-q`:** only the PIDs, one per line, for `slicc tray -q | xargs kill`. There's no `stop`.
1378
1379
  - **`-a`:** also the trays this machine knows but isn't following now, from `tray-certs.json` and `tray-join.json`, as `docker ps -a` does: PID `-`, state `not running`, the leader's name from the last link and the device for that hub. Neither file's join URL is shown.
1379
1380
 
@@ -1387,7 +1388,12 @@ PID MODE SEVEN DEVICE STATE OFFERS
1387
1388
  - **macOS and Linux:** the directory is `0700`, must belong to the user and not be a symlink, and is tightened when it's more open. Each connection checks the peer's uid (`SO_PEERCRED` on Linux, `LOCAL_PEERCRED` on macOS) and closes on anyone else.
1388
1389
  - **Windows:** slicc sets the directory's DACL to the user and SYSTEM only, protected from inheritance, so the sockets in it inherit it. `slicc tray` skips a directory whose DACL is anything else.
1389
1390
  - **Either way,** a process that can't serve a socket there runs on without one.
1390
- - **The protocol:** one line of JSON each way, `{ "v": 1, "op": "status" }` and the status object above, then the process closes the connection.
1391
+ - **The protocol:** one line of JSON each way, then the process closes the connection. The ops, same-uid only as above:
1392
+ - `{ "v": 1, "op": "status" }`, answered with the status object above. Its `ops` lists the ops this process answers, `status` first, so a client can tell what a running `slicc` of another version supports; a process from before `ops` existed answers only `status`.
1393
+ - `{ "v": 1, "op": "stop" }`: exactly what `SIGTERM` does. The process says `bye` to seven, closes the browsers this run launched, and exits 0; `closed.browsers` lists them with `--json`.
1394
+ - `{ "v": 1, "op": "detach" }`: the process says `bye` to seven, stops the link, and leaves every browser running, the ones it launched too; with `--json`, `closed` has `browsers: []` and `kept`, the ids of the launched browsers left running (`[]` on `attach`, `open`, `pair` and `follow`, which launch none). A kept browser is found again by the next run: its `DevToolsActivePort` in its SLICC profile leads discovery to it with its seven tab open, and the next `slicc` attaches to it (`attached` with no `launched`) and links that tab.
1395
+ - `stop` and `detach` are answered `{ "v": 1, "ok": true }` before the process acts. A process that doesn't know an op answers `{ "v": 1, "error": "EINVAL" }`, and a line that isn't a request of version 1 gets `EPROTO`.
1396
+ - Signals don't change: `SIGINT` and `SIGTERM` still stop, except that `slicc --keep-browsers` makes `SIGTERM` detach.
1391
1397
  - **Stale sockets:** liveness comes from connecting, not from the PID, so a reused PID can't fool `slicc tray`. A socket that refuses a connection is stale, and `slicc tray` removes it and says so on stderr, as `screen -wipe` does.
1392
1398
  - **The lock:** each process holds an `flock` on `<pid>.sock.lock` while it runs, and `slicc tray` removes a socket only while it holds that lock itself and the socket still refuses. So it never removes a live socket.
1393
1399
  - **A lock file deleted underneath:** both sides check after locking that the lock file on disk is still the one they hold, and start over when it isn't.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ai-ecoverse/slicc",
3
- "version": "1.52.0",
3
+ "version": "1.53.0",
4
4
  "description": "SLICC's command line for seven: links a machine's network, compute and browsers to seven over WebRTC",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -18,12 +18,12 @@
18
18
  "node": ">=18"
19
19
  },
20
20
  "optionalDependencies": {
21
- "@ai-ecoverse/slicc-darwin-arm64": "1.52.0",
22
- "@ai-ecoverse/slicc-darwin-amd64": "1.52.0",
23
- "@ai-ecoverse/slicc-linux-arm64": "1.52.0",
24
- "@ai-ecoverse/slicc-linux-amd64": "1.52.0",
25
- "@ai-ecoverse/slicc-windows-arm64": "1.52.0",
26
- "@ai-ecoverse/slicc-windows-amd64": "1.52.0",
21
+ "@ai-ecoverse/slicc-darwin-arm64": "1.53.0",
22
+ "@ai-ecoverse/slicc-darwin-amd64": "1.53.0",
23
+ "@ai-ecoverse/slicc-linux-arm64": "1.53.0",
24
+ "@ai-ecoverse/slicc-linux-amd64": "1.53.0",
25
+ "@ai-ecoverse/slicc-windows-arm64": "1.53.0",
26
+ "@ai-ecoverse/slicc-windows-amd64": "1.53.0",
27
27
  "@ai-ecoverse/slicc-jerk": "^1.3.9"
28
28
  }
29
29
  }