@ai-ecoverse/slicc 1.51.2 → 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 +59 -19
  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.
@@ -330,7 +330,7 @@ Release builds (a plain `X.Y.Z` version, linked in or, for `go install`, from th
330
330
  slicc capabilities [--json]
331
331
  ```
332
332
 
333
- `slicc capabilities --json` is the handshake of a program that drives `slicc`, such as a native app: one JSON document on stdout, from the binary's own tables, so it describes exactly the `slicc` it came from. It reads no files, asks no network, sends no telemetry and prints no update notice, so it works the same inside an app bundle. Without `--json` it prints the version, the contract and a table of the commands.
333
+ `slicc capabilities --json` is the handshake of a program that drives `slicc`, such as a native app: one JSON document on stdout, from the binary's own tables, so it describes exactly the `slicc` it came from. It runs before anything else `slicc` does at start: it reads no files (not even slicc's data folder, which other commands look at for companion tools), asks no network, sends no telemetry and prints no update notice, so it works the same inside an app bundle, with no home directory at all. Without `--json` it prints the version, the contract and a table of the commands.
334
334
 
335
335
  ```
336
336
  {"schema":1,"version":"<slicc version>","contract":1,"commands":{"<name>":{"json":"document"|"events"|"none","vocabulary"?:"events"|"agent"}},"events":{"schema":1,"names":[…]},"agent":{"events":[…],"own":[…]},"control":{"v":1,"ops":["status",…]}}
@@ -344,18 +344,49 @@ 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
+
349
+ ### Lifecycle events: `--json` on `attach`, `open`, `pair` and `follow`
350
+
351
+ With `--json`, `attach`, `open`, `pair` (and `--default-browser`, which is `open`) and `follow` print the NDJSON of [the default's `--json`](#the-default-slicc) on stdout: one event a line, each with `"schema": 1` and `event`, from the same vocabulary. stdout carries nothing else: `open` and `pair` put the pairing URL in a `pairing` event instead of a line of its own. Status lines stay on stderr, and so does every error, which also comes as an `error` event. Fields marked `?` are left out when empty. New fields and events may be added, and existing ones keep their meaning. Without `--json` nothing changes.
352
+
353
+ - `connecting`: `mode`, `attempt?`. A dial or setup starts: for `attach`, the CDP connection (`mode` `cdp`), then each offer from seven; for `open` and `pair`, each offer (`loopback`); for `follow`, each dial of the tray hub (`tray`), with `attempt` from the first reconnect on, the `attempt` of the `reconnecting` before it.
354
+ - `pairing`: `url`, on `open` and `pair`, for the first pairing URL and each new one (Enter on stdin). It is never a join URL. The pairing URL holds a one-time token and works as a secret for 10 minutes; it is printed by design, as without `--json`.
355
+ - `linked`: `mode`, `peer?` (the name in seven's HELLO), `tab?` (the page's origin, for `attach`), `device?` (the page's certificate fingerprint, for `open` and `pair`), `caps`, `policy` (the summary), and `resources`, what this link offers, as seven sees it:
356
+ - `browsers`: `[{"id","name","role","owned"}]`, the browsers listed for `cdp` (`role` `seven` or `extra`; `owned` is `true` for a browser this run launched, so never on these commands); `[]` without `cdp`;
357
+ - `mounts`: `[{"name","path","readOnly"}]`, the folders shared over `fs`, with the resolved path on this machine;
358
+ - `rejectedMounts`: `[{"path","reason"}]`, the `--mount` folders left out, with `path` as given and `reason` `not-a-folder`, `fenced` (slicc never shares it, see [Host folders](#host-folders)), `invalid-name` or `name-taken`;
359
+ - `network`: `{"exit","policy"}`, whether `net` goes out from this machine, and the policy summary;
360
+ - `compute`: `{"ssh","sftp"}`;
361
+ - `jerk`: `{"offered","seal"}`, the `jerk` and `jerk-seal` caps;
362
+ - `kernelPort?`: the local port of [kernel services](#kernel-services), when they are on.
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
+ - `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
+ - `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, and `kept: []` after the control socket's `detach`.
367
+
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
+
370
+ ```
371
+ {"schema":1,"event":"connecting","mode":"tray"}
372
+ {"schema":1,"event":"linked","mode":"tray","peer":"seven","caps":["net","http","credentialed","ws","udp","fs","join"],"policy":"every public address","resources":{"browsers":[],"mounts":[{"name":"proj","path":"/Users/me/proj","readOnly":true}],"rejectedMounts":[],"network":{"exit":true,"policy":"every public address"},"compute":{"ssh":false,"sftp":false},"jerk":{"offered":false,"seal":false}}}
373
+ {"schema":1,"event":"link-lost","mode":"tray"}
374
+ {"schema":1,"event":"reconnecting","attempt":1,"retryAt":"2026-05-02T10:00:01Z","wait":1043}
375
+ {"schema":1,"event":"connecting","mode":"tray","attempt":1}
376
+ {"schema":1,"event":"error","message":"seven's tray has expired; get a new join URL from seven","code":"TRAY_EXPIRED","retryable":false}
377
+ {"schema":1,"event":"closed","browsers":[]}
378
+ ```
348
379
 
349
380
  ## The default: `slicc`
350
381
 
351
382
  ```
352
383
  slicc [--browser <id>]... [--cdp <url>]... [--page <url>] [--origin <origin>]... [--profile <name> | --profile six[:<port>]] [--headless]
353
384
  [--name <name>] [--kernel-port <n>] [--no-kernel] [--allow <rule>]... [--deny <rule>]... [--expose-debug-port <port>]... [--mount <path>[:<name>][:ro]]...
354
- [--yes] [--plain] [--json] [--no-fallback] [--open] [--default-browser]
385
+ [--yes] [--plain] [--json] [--no-fallback] [--open] [--default-browser] [--keep-browsers]
355
386
  [--runner <argv…> [--]] [--shell <argv…> [--]] [--eval <argv…> [--]] [--eval-quiet <dur>] [--sftp | --no-sftp]
356
387
  ```
357
388
 
358
- `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.
359
390
 
360
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).
361
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.
@@ -364,6 +395,7 @@ slicc [--browser <id>]... [--cdp <url>]... [--page <url>] [--origin <origin>]...
364
395
  - **`--json` events** in this mode, with the shapes of the other modes plus `mode: "loopback"` and `device` (the page's certificate fingerprint):
365
396
  - `linked`: `peer?`, `caps` and `policy`, for each link that comes up;
366
397
  - `link-lost`: `reason?` or `message?`, for each one that goes;
398
+ - `error` with `message` and `retryable: false` when the loopback setup fails (no free port, say), then `closed`;
367
399
  - `closed`, with `browsers: []`, last, when slicc exits.
368
400
  - **Then** it serves loopback links with this run's `--page`, `--origin`, `--name`, `--allow`, `--deny`, `--expose-debug-port`, `--kernel-port`, `--no-kernel`, `--no-jerk`, `--mount` and compute flags, until `SIGINT` or `SIGTERM`.
369
401
 
@@ -388,6 +420,7 @@ The cdp list follows the browsers: an extra that stops answering is taken off th
388
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)).
389
421
  - `--headless`: launch browsers without a window.
390
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.
391
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.
392
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)).
393
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.
@@ -421,7 +454,7 @@ The cdp list follows the browsers: an extra that stops answering is taken off th
421
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.
422
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.
423
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`.
424
- - `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.
425
458
  - `error`: `message`, and `browser?` when closing that browser failed. A setup error ends the run with exit 1.
426
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: []`.
427
460
  - `pairing`: `url`, a pairing URL, after `mode`.
@@ -536,24 +569,24 @@ Launches a browser with CDP and keeps running until interrupted (Ctrl-C, `SIGINT
536
569
  - Before each launch, the seven prefs are merged into the profile's `Default/Preferences`, which is created if missing: `tab_freezing_enabled: false`, `performance_tuning.tab_freezing.enabled: false`, Memory Saver off (`performance_tuning.high_efficiency_mode.state: 0`), and `[*.]sliccy.ai` plus each extra allowed origin's host as tab-discard exceptions. The exceptions go into the list `performance_tuning.tab_discarding.exceptions` (six's form) and into the map `performance_tuning.tab_discarding.exceptions_with_time`, which Chrome 154 reads and shows under "Always keep these sites active". Existing keys, exceptions and timestamps are kept, and a file that already has everything isn't rewritten. A Preferences file that isn't a JSON object is left alone. `--no-seven-flags` skips these prefs too.
537
570
  - Chromium flags: `--remote-debugging-port=0 --user-data-dir=<profile> --no-first-run --no-default-browser-check`, the throwaway flags for a throwaway profile, the seven flags below, `--headless=new` with `--headless`, then `--url`.
538
571
  - A throwaway profile is one inside the system temp dir (Go's `os.TempDir()`: `TMPDIR` on macOS and Linux, `TMP` or `TEMP` on Windows; symlinks resolved, case ignored on macOS and Windows). It gets `--use-mock-keychain --password-store=basic` (`browser.ThrowawaySwitches`), so Chrome never asks for the macOS keychain or a Linux password store; without a default keychain, as under a temporary `HOME`, macOS would show "Keychain Not Found". Every other profile, SLICC's and six's included, headless or not, keeps the real keychain, so its saved cookies and passwords stay readable. `browser.Throwaway(dir)` tells which is which.
539
- - The seven flags keep a seven tab's kernel running while the tab is in the background: `--disable-background-timer-throttling`, `--disable-backgrounding-occluded-windows`, `--disable-renderer-backgrounding`, `--disable-background-tracing`, and `--disable-features=LocalNetworkAccessChecks,LocalNetworkAccessChecksWebSockets,IntensiveWakeUpThrottling,HighEfficiencyModeAvailable,InfiniteTabsFreezing,InfiniteTabsFreezingOnMemoryPressure,CPUMeasurementInFreezingPolicy,MemoryMeasurementInFreezingPolicy,AllowDevtoolsConnectedDiscard`. Chromium ignores feature names it doesn't know. Every Chromium browser slicc launches, with or without the seven flags, also gets `--enable-features=ForceForegroundPriorityForAllTabs`, merged with any other `--enable-features` into one switch since Chromium keeps only the last, so a loaded Mac doesn't move a hidden tab's renderer into the background priority band, where the guard can't hear from it within 30 s and refuses the tab. `--no-seven-flags` (`LaunchOptions.NoSevenFlags`) leaves them all out, along with the seven prefs above, but not `--enable-features=ForceForegroundPriorityForAllTabs`, because the guard watches every browser slicc launches, not only seven's. Chromium keeps only one `--disable-features` value, so every `--disable-features` from the seven flags and from `LaunchOptions.ExtraArgs` is merged into one switch, in order and without duplicates. The CDP port is read from the profile's `DevToolsActivePort` once `/json/version` answers with the same websocket path. slicc waits for that as long as the browser it started is running, up to 2 min, since a first start from a cold or slow disk can take well over 30 s. Every 10 s of the wait it says so: `slicc: Google Chrome is still starting (slow disk?), 10 s so far` on stderr, or the `browser-slow` event with `--json`. A browser that exits first fails the launch at once, with its exit code and the end of its output (`Google Chrome exited with code 21 after 0.4s, before writing DevToolsActivePort; its output: …`). One still running after 2 min is stopped, and the launch fails with `… is still running after 2m0s but has not written <profile>/DevToolsActivePort`. Ctrl-C, `SIGINT` or `SIGTERM` during the wait stops the browser at once, and `slicc launch` says `slicc: interrupted while <name> was starting; closed it` (`{"event":"closed"}` with `--json`) and exits 0. A browser that `open` started on macOS isn't a child of slicc, so a launch that fails or is interrupted also stops the processes that hold the profile: the `SingletonLock` owner and every process started with its `--user-data-dir`. For an Electron app, which has no SLICC profile, it stops the process running the app's executable; the launch refuses an app that is already running, so that process is the one slicc started. One that is still running 15 s later is named in the error (`… is still running as process [<pid>]`), and `slicc launch` exits 1 instead of reporting `closed`. Electron apps get the same wait for their CDP port. On macOS a browser with a window starts through `open -n -W -a <app> --args …`, so camera and microphone permissions belong to the browser, not the terminal; `--headless` runs the executable directly. A flatpak starts with `flatpak run --filesystem=<profile> <id>`.
572
+ - The seven flags keep a seven tab's kernel running while the tab is in the background: `--disable-background-timer-throttling`, `--disable-backgrounding-occluded-windows`, `--disable-renderer-backgrounding`, `--disable-background-tracing`, and `--disable-features=LocalNetworkAccessChecks,LocalNetworkAccessChecksWebSockets,IntensiveWakeUpThrottling,HighEfficiencyModeAvailable,InfiniteTabsFreezing,InfiniteTabsFreezingOnMemoryPressure,CPUMeasurementInFreezingPolicy,MemoryMeasurementInFreezingPolicy,AllowDevtoolsConnectedDiscard`. Chromium ignores feature names it doesn't know. Every Chromium browser slicc launches, with or without the seven flags, also gets `--enable-features=ForceForegroundPriorityForAllTabs`, merged with any other `--enable-features` into one switch since Chromium keeps only the last, so a loaded Mac doesn't move a hidden tab's renderer into the background priority band, where the guard can't hear from it within 30 s and refuses the tab. `--no-seven-flags` (`LaunchOptions.NoSevenFlags`) leaves them all out, along with the seven prefs above, but not `--enable-features=ForceForegroundPriorityForAllTabs`, because the guard watches every browser slicc launches, not only seven's. Chromium keeps only one `--disable-features` value, so every `--disable-features` from the seven flags and from `LaunchOptions.ExtraArgs` is merged into one switch, in order and without duplicates. The CDP port is read from the profile's `DevToolsActivePort` once `/json/version` answers with the same websocket path. slicc waits for that as long as the browser it started is running, up to 2 min, since a first start from a cold or slow disk can take well over 30 s. Every 10 s of the wait it says so: `slicc: Google Chrome is still starting (slow disk?), 10 s so far` on stderr, or the `browser-slow` event with `--json`. A browser that exits first fails the launch at once, with its exit code and the end of its output (`Google Chrome exited with code 21 after 0.4s, before writing DevToolsActivePort; its output: …`). One still running after 2 min is stopped, and the launch fails with `… is still running after 2m0s but has not written <profile>/DevToolsActivePort`. Ctrl-C, `SIGINT` or `SIGTERM` during the wait stops the browser at once, and `slicc launch` says `slicc: interrupted while <name> was starting; closed it` (`{"schema":1,"event":"closed"}` with `--json`) and exits 0. A browser that `open` started on macOS isn't a child of slicc, so a launch that fails or is interrupted also stops the processes that hold the profile: the `SingletonLock` owner and every process started with its `--user-data-dir`. For an Electron app, which has no SLICC profile, it stops the process running the app's executable; the launch refuses an app that is already running, so that process is the one slicc started. One that is still running 15 s later is named in the error (`… is still running as process [<pid>]`), and `slicc launch` exits 1 instead of reporting `closed`. Electron apps get the same wait for their CDP port. On macOS a browser with a window starts through `open -n -W -a <app> --args …`, so camera and microphone permissions belong to the browser, not the terminal; `--headless` runs the executable directly. A flatpak starts with `flatpak run --filesystem=<profile> <id>`.
540
573
  - Electron apps keep their own data and get `--remote-debugging-port=<port>`, the first free port from 9333 up, so they never take 9222–9229. An app that is already running is refused, since a second instance would hand off to it; quit it first. Apps with `debugSupport: "disabled"` are refused.
541
574
  - Shutdown: `Browser.close` over CDP; if the browser is still running 5 s later, a signal (`SIGTERM` to the browser's process group and main process; `taskkill /T` on Windows), then after 3 s a kill (`SIGKILL`; `taskkill /F /T`). The browser runs in its own process group (`CREATE_NEW_PROCESS_GROUP` on Windows), so a terminal Ctrl-C reaches only `slicc`.
542
575
 
543
- Plain output: the CDP HTTP URL on stdout, status lines on stderr. With `--json`, NDJSON events on stdout:
544
- - `{"event":"launched","id","name","version","engine","pid","profile","profileDir","cdp","webSocketDebuggerUrl"}` (`version`, `profile` and `profileDir` are left out when empty);
545
- - `{"event":"browser-slow","id","name","elapsed"}` every 10 s while the browser is still starting (`elapsed` in seconds, see above);
546
- - `{"event":"closed"}` after `slicc launch` closed the browser;
547
- - `{"event":"exited"}` when the browser exited by itself;
548
- - with `--profile six`, when six's Chrome was already running: `{"event":"attached","id","name","version","engine","profile","profileDir","cdp","webSocketDebuggerUrl"}` instead of `launched`, then `{"event":"detached"}` on Ctrl-C (six's Chrome keeps running) or `exited` when it quits;
549
- - `{"event":"error","message"}`, then exit 1.
576
+ Plain output: the CDP HTTP URL on stdout, status lines on stderr. With `--json`, NDJSON events on stdout, each with `"schema": 1` and `event`, as in [the default's `--json`](#the-default-slicc) (earlier releases left `schema` out):
577
+ - `{"schema":1,"event":"launched","id","name","version","engine","pid","profile","profileDir","cdp","webSocketDebuggerUrl"}` (`version`, `profile` and `profileDir` are left out when empty);
578
+ - `{"schema":1,"event":"browser-slow","id","name","elapsed"}` every 10 s while the browser is still starting (`elapsed` in seconds, see above);
579
+ - `{"schema":1,"event":"closed"}` after `slicc launch` closed the browser;
580
+ - `{"schema":1,"event":"exited"}` when the browser exited by itself;
581
+ - with `--profile six`, when six's Chrome was already running: `{"schema":1,"event":"attached","id","name","version","engine","profile","profileDir","cdp","webSocketDebuggerUrl"}` instead of `launched`, then `{"schema":1,"event":"detached"}` on Ctrl-C (six's Chrome keeps running) or `exited` when it quits;
582
+ - `{"schema":1,"event":"error","message"}`, then exit 1.
550
583
 
551
584
  ## Local setup: `slicc attach`
552
585
 
553
586
  ```
554
587
  slicc attach --cdp <url> [--cdp-extra <url>]... [--origin <origin>]... [--signal cdp|stdio] [--name <name>] [--allow <rule>]... [--deny <rule>]... [--expose-debug-port <port>]...
555
588
  [--runner <argv…> [--]] [--shell <argv…> [--]] [--eval <argv…> [--]] [--eval-quiet <dur>] [--sftp | --no-sftp] [--kernel-port <n>] [--no-kernel]
556
- [--mount <path>[:<name>][:ro]]...
589
+ [--mount <path>[:<name>][:ro]]... [--json]
557
590
  ```
558
591
 
559
592
  `attach` links a seven that is open in a running CDP browser and serves the link until it is interrupted (`SIGINT`, `SIGTERM`), or until stdin closes with `--signal stdio`. Status lines go to stderr, and `SLICC_DEBUG=1` adds diagnostics, pion's included. pion never writes to stderr itself.
@@ -574,6 +607,7 @@ slicc attach --cdp <url> [--cdp-extra <url>]... [--origin <origin>]... [--signal
574
607
  - `--kernel-port`: the local port for [kernel services](#kernel-services) (1–65535, default `80`; with `80`, a spare port in 17180–17189 when `80` can't be bound).
575
608
  - `--no-kernel`: no kernel services; nothing listens.
576
609
  - `--no-jerk`: don't offer this machine's slicc-jerk (caps `jerk` and `jerk-seal`, see [`jerk`](#jerk-slicc-jerk-over-the-link)).
610
+ - `--json`: NDJSON lifecycle events on stdout (see [Lifecycle events](#lifecycle-events---json-on-attach-open-pair-and-follow)). Not with `--signal stdio`, whose setup messages own stdout (exit 2).
577
611
 
578
612
  **Setup over CDP.**
579
613
  1. slicc picks the first page tab whose URL has an allowed origin. Until there is one it says `waiting for a seven tab` and watches for new tabs. After 15 s without one it says `still no seven tab` and what to do: a browser can hide seven's own tab from debugging clients, and then this setup can't work, so link through the tray ([Remote setup](#remote-setup-slicc-join-url-follow)). `SLICC_SEVEN_QUIET` (test-only, a Go duration) replaces the 15 s. A `Target.createTarget` refused by such a browser ends plain `slicc` with the same advice.
@@ -609,7 +643,7 @@ slicc attach --cdp <url> [--cdp-extra <url>]... [--origin <origin>]... [--signal
609
643
  ```
610
644
  slicc open [--page <url>] [--origin <origin>]... [--name <name>] [--allow <rule>]... [--deny <rule>]... [--expose-debug-port <port>]...
611
645
  [--kernel-port <n>] [--no-kernel] [--no-jerk] [--mount <path>[:<name>][:ro]]...
612
- [--runner <argv…> [--]] [--shell <argv…> [--]] [--eval <argv…> [--]] [--eval-quiet <dur>] [--sftp | --no-sftp]
646
+ [--runner <argv…> [--]] [--shell <argv…> [--]] [--eval <argv…> [--]] [--eval-quiet <dur>] [--sftp | --no-sftp] [--json]
613
647
  slicc pair [the same flags]
614
648
  slicc --default-browser [the same flags]
615
649
  slicc unpair [<fingerprint> | --all]
@@ -1160,7 +1194,7 @@ A command that can't start exits 127 with the reason on stderr.
1160
1194
  ```
1161
1195
  slicc <join-url> follow [--exit] [--allow <rule>]... [--deny <rule>]... [--expose-debug-port <port>]... [--name <name>] [--cdp <url>]...
1162
1196
  [--runner <argv…> [--]] [--shell <argv…> [--]] [--eval <argv…> [--]] [--eval-quiet <dur>] [--sftp | --no-sftp]
1163
- [--mount <path>[:<name>][:ro]]... [--jerk] [--jerk-seal]
1197
+ [--mount <path>[:<name>][:ro]]... [--jerk] [--jerk-seal] [--json]
1164
1198
  slicc - follow [flags]
1165
1199
  slicc @<file> follow [flags]
1166
1200
  ```
@@ -1174,6 +1208,7 @@ slicc @<file> follow [flags]
1174
1208
  - `--allow`, `--deny`: policy rules on top of the remote default (see [Network policy](#network-policy)). This machine's debugging ports stay denied on every address of it, whatever `--allow` says, `--allow 127.0.0.1/32` included.
1175
1209
  - `--expose-debug-port <port>`: let seven reach this one debugging port after all (repeatable), as for `attach`. The `--cdp` ports stay denied.
1176
1210
  - `--name`: the link's `name` and `host` in HELLO, as for `attach`.
1211
+ - `--json`: NDJSON lifecycle events on stdout (see [Lifecycle events](#lifecycle-events---json-on-attach-open-pair-and-follow)). Not with `--signal-only` (exit 2).
1177
1212
  - `--runner`, `--shell`, `--eval`, `--eval-quiet`, `--sftp`, `--no-sftp`: compute over SSH (cap `ssh`), exactly as for `attach`. `direct-tcpip` forwarding goes through the remote policy, so it reaches public addresses only unless `--allow` says otherwise. `--runner` works with or without `--exit`.
1178
1213
  - `--cdp <url>`: let seven drive this browser over the link (repeatable, in any form `slicc browsers --cdp` takes; each must answer when `follow` starts). See [`cdp`](#cdp-browser-control), and its warning: the seven on the other machine gets full control of every browser listed. No browser is `seven: true`. Without `--cdp`, `follow` doesn't offer `cdp`, and a `cdp` OPEN is refused with `EOPNOTSUPP`. Each browser's debugging port and its own endpoint addresses are [denied](#network-policy) to `tcp`, `http`, `ws`, `udp` and `ssh` forwarding.
1179
1214
  - `--mount <path>[:<name>][:ro]`: share this folder with the seven on the other machine (cap `fs`, repeatable); see [Host folders](#host-folders). It can read the folder, and change it unless `:ro`.
@@ -1339,7 +1374,7 @@ PID MODE SEVEN DEVICE STATE OFFERS
1339
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 (`-`).
1340
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.
1341
1376
  - **`OFFERS`:** `exit` (the network, `--exit` for `follow`), `ssh`, `cdp`, `jerk`, `fs:<name>` per folder, and `kernel:<port>`.
1342
- - **`--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.
1343
1378
  - **`-q`:** only the PIDs, one per line, for `slicc tray -q | xargs kill`. There's no `stop`.
1344
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.
1345
1380
 
@@ -1353,7 +1388,12 @@ PID MODE SEVEN DEVICE STATE OFFERS
1353
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.
1354
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.
1355
1390
  - **Either way,** a process that can't serve a socket there runs on without one.
1356
- - **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.
1357
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.
1358
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.
1359
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.51.2",
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.51.2",
22
- "@ai-ecoverse/slicc-darwin-amd64": "1.51.2",
23
- "@ai-ecoverse/slicc-linux-arm64": "1.51.2",
24
- "@ai-ecoverse/slicc-linux-amd64": "1.51.2",
25
- "@ai-ecoverse/slicc-windows-arm64": "1.51.2",
26
- "@ai-ecoverse/slicc-windows-amd64": "1.51.2",
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
  }