sliccy 6.141.0 → 6.141.2

package/dist/ui/assets/{jsh-runtime-extensions-BA7Q4hGB.js → jsh-runtime-extensions-6coWmZ2q.js}

@@ -1 +1 @@
-var e="# jsh runtime extensions\n\nThis file is bundled into the agent VFS at `/workspace/skills/skill-authoring/jsh-runtime-extensions.md`. Developer-facing equivalent: `docs/shell-reference.md` (which lives outside the VFS). Keep both in sync when the runtime surface changes.\n\n## Runtime globals (Globals API)\n\nEvery `.jsh` script runs in an async wrapper with a small Node-standard surface available as bare globals. SLICC's capability bridges (exec, agent, http, browser, USB / Serial / HID, skill, color, cli, time, fmt, pool) are NOT bare globals; they are reached via the `sliccy:` virtual-module scheme below.\n\n### Node-standard bare globals\n\n| Global                                                           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `process`                                                        | `argv` (with `.parseFlags()`), `env`, `cwd()`, `exit(code)`, `stdout.write`, `stderr.write`. `stdin` is a fully-buffered (no streaming) one-shot value with three surfaces sharing one `consumed` flag — `read()` (returns `null` when nothing was piped, Node parity), events (`on('data')`→`'end'`→`'close'`, single chunk, no real streaming — `pause()` suppresses emission until `resume()`, and `exit(N)` from a handler exits with code `N`), and async iterator. Drain via exactly one; the others then see EOF. |\n| `console`                                                        | `log`/`info` → stdout, `warn`/`error` → stderr.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| `fetch`                                                          | Standard `fetch` routed through SLICC's proxied transport (cookies + CORS + secret masking handled). Binary bodies (`Uint8Array` / `Blob` / `FormData`) are sent as raw bytes — bytes ≥0x80 are not UTF-8-expanded. `await res.json()` / `res.text()` resolve from the already-buffered body and keep the realm alive for the rest of the continuation.                                                                                                                                                                  |\n| `require(p)`                                                     | Synchronous CJS `require`. Use `require('sliccy:<name>')` for capability bridges, `require('fs')` / `require('node:fs')` for the VFS bridge, `require('<pkg>')` for installed packages.                                                                                                                                                                                                                                                                                                                                  |\n| `Buffer` / `globalThis`                                          | Node-standard surface.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `setTimeout` / `clearTimeout` / `setInterval` / `queueMicrotask` | Web timer surface (also reachable through `globalThis`). Outstanding timeouts and intervals keep the realm alive the way Node keeps a process alive for ref'd handles; `queueMicrotask` is not a handle. `process.exit()` cancels pending timers.                                                                                                                                                                                                                                                                        |\n| `__dirname` / `__filename`                                       | CJS scope vars — the running script's own directory and absolute path.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `module` / `exports`                                             | CJS module record (writeable; useful when a `.jsh` is treated as a library by a sibling `require('./helper.jsh')`).                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `process.argv.parseFlags()`                                      | Parse `--flag=val` / `--flag val` / `-x` / positional / `--` passthrough into `{ positional, flags, subcommand, passthrough }`.                                                                                                                                                                                                                                                                                                                                                                                          |\n\n### Capability bridges — `sliccy:` virtual modules\n\nThe bespoke globals are hard-cut. Reach each capability via `require('sliccy:<name>')` (CJS) or `import ... from 'sliccy:<name>'` (ESM). `require('fs')` / `require('node:fs')` keeps returning the VFS bridge.\n\n| `require('sliccy:<name>')`                    | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `sliccy:exec`                                 | Callable `exec(cmd)` plus `.spawn(argv[])`, `.start(cmdOrArgv, opts?)` (killable, buffered-stdin spawn handle) and `.exec` self-reference. Returns `{ stdout, stderr, exitCode }`. Use `const { exec } = require('sliccy:exec')` or `const exec = require('sliccy:exec')`.                                                                                                                                                 |\n| `sliccy:agent`                                | Callable `agent(prompt, opts?)` — spawns a one-shot sub-scoop, feeds it the prompt, blocks until the agent loop completes; resolves to trimmed final text (JSON-parsed when `opts.schema` is set), REJECTS on non-zero exit or schema-parse failure. `.spawn(prompt, opts?)` is the non-throwing variant → `{ finalText, exitCode, stderr }`. `opts`: `model`, `thinking`, `cwd`, `allowedCommands`, `readOnly`, `schema`. |\n| `sliccy:skill`                                | Frozen `{ dir, root, refs, assets, config(), config(updates), token(providerId) }`. `refs`/`assets` resolve from the skill root (parent of `scripts/` when the script lives there). Replaces ad-hoc `argv[1]` dirname math and `oauth-token` shell-outs.                                                                                                                                                                   |\n| `sliccy:http`                                 | `http.client({ baseUrl, token, headers, retry, timeoutMs })` builder.                                                                                                                                                                                                                                                                                                                                                      |\n| `sliccy:browser`                              | `findTab`, `ensureTab`, `eval`, `evalAsync`, `cookie`, `localStorage`, `fetch`, `websocket.on(...).filter(...).forward(...)`.                                                                                                                                                                                                                                                                                              |\n| `sliccy:usb` / `sliccy:serial` / `sliccy:hid` | `list()` / `request()` + device methods (`open`/`close`/`sendReport`/...). Chromium-only.                                                                                                                                                                                                                                                                                                                                  |\n| `sliccy:cli`                                  | `die(msg, opts?)`, `out(value)`, `warn(msg, opts?)`, `help(text)`. `opts` is `number` or `{ exitCode?, prefix? }`; `prefix: ''` removes the default `Error:` / `Warning:` label entirely.                                                                                                                                                                                                                                  |\n| `sliccy:color`                                | ANSI helpers: `green`, `red`, `yellow`, `gray`, `bold`, `cyan`, `dim`, plus `enabled` flag (auto-disabled on non-TTY / `NO_COLOR`).                                                                                                                                                                                                                                                                                        |\n| `sliccy:time`                                 | `parseDuration(spec)`, `ago(spec)`, `range(spec)`, `future(spec)`, `gmailDate(spec)`. Units: `ms s m h d w M y` (note: `m` = minutes, `M` = months).                                                                                                                                                                                                                                                                       |\n| `sliccy:fmt`                                  | `trunc(s, n)`, `col(s, width)`, `table(rows, widths?)`, `date(value, style?)`. `style`: `'short' \\| 'iso' \\| 'human' \\| 'locale'` (locale = `Intl.DateTimeFormat` medium).                                                                                                                                                                                                                                                 |\n| `sliccy:pool`                                 | `pool(n, items, fn)` — bounded concurrency runner, results returned in input order.                                                                                                                                                                                                                                                                                                                                        |\n\n`require('sliccy:<unknown>')` throws a scheme-specific error (`Unknown sliccy: module '<name>'`); empty `require('sliccy:')` throws `empty sliccy: module name`. `sliccy:` lookups never hit the registry / `node_modules` / `ipk install`.\n\n### Filesystem (VFS bridge)\n\n`require('fs')` and `require('node:fs')` return the VFS bridge (`readFile`, `writeFile`, `readFileBinary`, `writeFileBinary`, `readDir`, `exists`, `stat`, `mkdir`, `rm`, `fetchToFile(url, path)`), plus the sync set (`readFileSync`, `writeFileSync`, `existsSync`, `statSync`, …). All paths are VFS-resolved. There is no bare `fs` global.\n\nStdio fds and device paths work like Node: `fs.readFileSync(0, 'utf8')` (or `'/dev/stdin'`) reads the full piped stdin without consuming `process.stdin`; `fs.writeFileSync(1, …)` / `fs.writeFileSync(2, …)` (or `/dev/stdout` / `/dev/stderr`) write to stdout/stderr; `existsSync`/`statSync` report the three stream devices as present. Unknown numeric fds and wrong-direction stream ops throw `EBADF`.\n\n### Line reading (`readline`)\n\n`require('readline')` and `require('readline/promises')` work over the buffered stdin:\n\n```javascript\nconst readline = require('readline/promises');\nconst rl = readline.createInterface({ input: process.stdin, output: process.stdout });\nfor await (const line of rl) console.log('>', line);\n// or: rl.on('line', fn) … rl.on('close', fn), or const answer = await rl.question('name? ')\n```\n\nCreating the interface drains `process.stdin` (one-shot, like Node's flowing mode); `question()` answers with the next unconsumed line (`''` at EOF).\n\n### Examples for the non-trivial globals\n\n```javascript\n// process.argv.parseFlags() — replace per-skill arg loops\nconst { positional, flags, subcommand, passthrough } = process.argv.parseFlags();\n// e.g. `mycli send --to alice --json -- --raw` →\n//   positional: ['send', 'alice'], flags: { to: 'alice', json: true },\n//   subcommand: 'send', passthrough: ['--raw']\n```\n\n**Two-level routing**: `parseFlags` populates `subcommand` only from the first positional. For `<cmd> <sub> [args]` CLIs, route the second level manually from `positional[1]`:\n\n```javascript\nconst { positional, flags } = process.argv.parseFlags();\nconst [cmd, sub] = positional;\nswitch (cmd) {\n  case 'pr':\n    if (sub === 'list') return prList(flags);\n    if (sub === 'view') return prView(positional[2], flags);\n    return cli.die(`unknown pr subcommand: ${sub}`);\n  // …\n}\n```\n\n```javascript\n// cli + color — early-exit helpers and color (both via sliccy:)\nconst cli = require('sliccy:cli');\nconst c = require('sliccy:color');\nif (!flags.to) cli.die('--to is required'); // writes \"Error: …\" to stderr, exits 1\ncli.out({ ok: true }); // pretty-prints JSON to stdout with trailing newline\nconsole.log(c.green('✓'), c.dim('done'));\n```\n\n```javascript\n// domain-specific prefix instead of the default \"Error:\"\nconst cli = require('sliccy:cli');\nif (!flags.repo) cli.die('--repo is required', { prefix: 'gh' });\n// → \"gh: --repo is required\"\ncli.warn('rate limit at 80%', { prefix: 'gh' });\n```\n\n```javascript\n// time — duration math\nconst time = require('sliccy:time');\nconst since = time.ago('7d'); // Date 7 days ago\nconst q = `after:${time.gmailDate('7d')}`; // \"after:2026/05/22\"\n\n// fmt — ANSI-aware table\nconst fmt = require('sliccy:fmt');\nconst c = require('sliccy:color');\nconsole.log(\n  fmt.table([\n    ['name', 'status'],\n    ['hub', c.green('up')],\n    ['relay', c.red('down')],\n  ])\n);\n\n// pool — bounded concurrency\nconst pool = require('sliccy:pool');\nconst results = await pool(4, urls, async (url) => (await fetch(url)).status);\n```\n\n```javascript\n// exec.spawn(argv[]) — bypass shell parsing. Use for any arg derived from\n// untrusted input: it can't be shell-interpolated.\nconst { exec } = require('sliccy:exec');\nconst userMessage = flags.message ?? 'wip';\nawait exec.spawn(['git', 'commit', '-m', userMessage]); // safe even with quotes/spaces in userMessage\n```\n\n```javascript\n// exec.start(cmdOrArgv, opts?) — killable, buffered-stdin spawn handle. Buffer\n// stdin with .write(), launch with .end(), await .done for the result, and\n// .kill(signal?) to abort. NOT interactive/streaming — just-bash is one-shot\n// buffered, so stdin is a single upfront buffer and post-launch writes drop.\nconst { exec } = require('sliccy:exec');\nconst h = exec.start(['jq', '.name']);\nh.stdin.write('{\"name\":\"slicc\"}');\nh.stdin.end();\nconst { stdout, exitCode } = await h.done;\n// h.kill('SIGTERM') fans a signal out via the exec:kill op.\n```\n\n```javascript\n// agent — spawn a one-shot sub-scoop and block on its result. The callable\n// resolves to the sub-scoop's final text; with `schema` it resolves to the\n// parsed object (rejects if the reply wasn't valid JSON) and rejects on a\n// non-zero exit. Use agent.spawn(...) when you want the raw outcome instead.\nconst agent = require('sliccy:agent');\nconst summary = await agent('Summarize /workspace/README.md in one line', {\n  thinking: 'low',\n  readOnly: '/workspace/',\n});\n\nconst parsed = await agent('Extract the title as {\"title\": string}', {\n  schema: { type: 'object', properties: { title: { type: 'string' } } },\n});\n\nconst { finalText, exitCode, stderr } = await agent.spawn('do the thing', {\n  model: 'claude-opus-4-6',\n  cwd: process.env.TMPDIR ?? '/tmp',\n  allowedCommands: 'git,node',\n});\n```\n\n### `require('child_process')` — Node process API over the exec bridge\n\n`require('child_process')` / `require('node:child_process')` resolves in the `.jsh` / `node` realm to a shim built on `exec.start`. `exec` / `execFile` / `spawn` map onto the one-shot just-bash exec pipeline: the returned `ChildProcess` is an `EventEmitter` that fires `'exit'` / `'close'`, and its `.stdout` / `.stderr` are Readable stubs that each emit a single `'data'` chunk then `'end'`. `exec` / `execFile` also carry a `util.promisify.custom` implementation resolving `{ stdout, stderr }`.\n\n```javascript\nconst { exec } = require('child_process');\nconst { promisify } = require('util');\nconst { stdout } = await promisify(exec)('ls -la /workspace');\n```\n\nThe **sync forms** (`execSync` / `spawnSync` / `execFileSync`) and `fork` throw — just-bash has no synchronous or long-lived process model. `.bsh` scripts (which run in the target page via CDP, not the realm) have no shell bridge at all, so `require('child_process')` there is unavailable; use `exec()` from a `.jsh` script instead.\n\n## jsh runtime extensions\n\nThe following capabilities collapse the boilerplate that 18 of 23 surveyed skills reinvented. They're available in both standalone and extension floats; each is reached through `require('sliccy:<name>')` (or the equivalent ESM `import`).\n\n### `sliccy:skill` — skill-root paths, config, tokens\n\nComputed once at boot from `argv[1]` and frozen. Replaces ad-hoc `process.argv[1].substring(0, …)` dirname math, bespoke `.config` JSON readers, and `oauth-token` shell-outs.\n\nAgent Skills layout is `<skill-root>/{SKILL.md,scripts/,references/,assets/}`. `skill.dir` is the directory containing the running script. When any path segment of that directory is `scripts` (`<skill-root>/scripts/<name>.jsh`, including helpers under `scripts/<subdir>/`), `skill.root` is the parent of that segment — the skill folder. Otherwise `skill.root` equals `skill.dir`. `skill.refs` and `skill.assets` resolve from `skill.root`. `skill.config()` still reads/writes `<dir>/.config` (typically `scripts/.config`) so `upskill` can preserve that dotfile.\n\n```typescript\nconst skill = require('sliccy:skill');\nskill.dir: string                                              // directory containing the running script\nskill.root: string                                             // skill folder (parent of `scripts/` when applicable)\nskill.refs: string                                             // `<root>/references`\nskill.assets: string                                           // `<root>/assets`\nskill.config(): Promise<Record<string, unknown> | null>        // read parsed JSON from `<dir>/.config`\nskill.config(updates): Promise<Record<string, unknown>>        // shallow-merge + write, returns merged\nskill.token(providerId: string): Promise<string>               // shells out to `oauth-token <id>`\n```\n\n```javascript\nconst skill = require('sliccy:skill');\nconst fs = require('fs');\nconst cfg = (await skill.config()) ?? {};\nconst token = await skill.token('adobe');\nconst tmpl = await fs.readFile(`${skill.refs}/prompt.md`);\n```\n\n### `sliccy:browser` — page-context CDP bridge\n\nReplaces the `exec('playwright-cli tab-list')` shell-out + regex parse used in ~12 skills. Accepts a `TabHandle` (from `findTab` / `ensureTab`) or a bare `targetId` string. `eval` / `evalAsync` serialize functions to a string call expression so realm code can pass a closure as ergonomically as a string.\n\n```typescript\nconst browser = require('sliccy:browser');\nbrowser.findTab(opts: { domain?: string; urlMatch?: RegExp | string }): Promise<TabHandle | null>\nbrowser.ensureTab(url: string, opts?: { matchUrl?: RegExp | string }): Promise<TabHandle>\nbrowser.eval(tab, fn: Function | string): Promise<unknown>      // sync expression\nbrowser.evalAsync(tab, fn: AsyncFunction): Promise<unknown>     // async, returns parsed JSON\nbrowser.cookie(tab, name: string): Promise<string | null>\nbrowser.localStorage(tab, key: string): Promise<string | null>\n```\n\n```javascript\nconst browser = require('sliccy:browser');\nconst cli = require('sliccy:cli');\nconst tab = await browser.findTab({ domain: 'slack.com' });\nif (!tab) cli.die('open slack.com first');\nconst team = await browser.eval(tab, () => document.title);\nconst xoxc = await browser.localStorage(tab, 'localConfig_v2');\n```\n\n### `browser.fetch(tab, url, opts)` — page-context fetch\n\nReplaces the eval-file + base64 + double-JSON-unwrap pattern in ~9 skills. Runs inside the tab's origin, so **session cookies and same-origin headers are automatic** — don't try to forward cookies manually.\n\n```typescript\nbrowser.fetch(tab: TabHandle | string, url: string, opts?: {\n  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | ...;\n  headers?: Record<string, string>;\n  body?: unknown;                   // object → JSON-stringified\n  credentials?: 'include' | 'omit'; // defaults to 'include'\n  responseType?: 'text' | 'json' | 'binary';\n  timeoutMs?: number;               // page-side AbortSignal.timeout()\n}): Promise<{\n  ok: boolean; status: number; statusText: string;\n  url: string; redirected: boolean; // final URL after redirects\n  headers: Record<string, string>;\n  body: unknown; bodyEncoding?: 'base64';\n}>\n```\n\nFrom the shell, `curlwright` is the same capability with curl's flags — reach for it while\nexploring an API, and for `browser.fetch` once the call is settled into a `.jsh`.\n\n```javascript\nconst browser = require('sliccy:browser');\nconst cli = require('sliccy:cli');\nconst resp = await browser.fetch(tab, '/api/conversations.list', {\n  method: 'POST',\n  body: { limit: 100 },\n});\nif (!resp.ok) cli.die(`slack ${resp.status}`);\nconst channels = resp.body.channels;\n```\n\n### `browser.websocket` — declarative WebSocket observer\n\nSanctioned replacement for `WebSocket.prototype.send` monkey-patches. **REQUIRED for any new WS-watch use case** — skill code MUST NOT author page-context functions that patch a third-party page's prototypes or see the inbound frame firehose.\n\n```typescript\nconst sub = await browser.websocket\n  .on(tab, { urlMatch: /wss-primary\\.slack\\.com/ })\n  .filter({ parseAs: 'json', where: { type: 'message', channel: 'C0899S7HV0E' } })\n  .forward({ sink: 'webhook', webhookId: 'slack-watch-abc123' });\n\nawait sub.update({ filter: { where: { channel: 'C-new' } } });\nawait sub.close();\nawait browser.websocket.list();\n```\n\n**Sink set is a closed enum.** The page-side router (runtime-owned, audited once) only knows how to forward matched frames to:\n\n- `'webhook'` — resolved against the existing `webhook` registry; an unknown `webhookId` rejects at subscriber-creation time.\n- `'scoop'` — delivered via the orchestrator's scoop dispatch.\n- `'vfs'` — appended to an absolute path that must start with `/workspace/`.\n- `'log'` — telemetry only.\n\n**Discovery requires outbound `send()`.** The router patches `WebSocket.prototype.send` as a pure discovery hook — it never observes outbound frames, but a WebSocket instance is only wrapped (and its inbound `message` listener attached) the first time something calls `send()` on it. Receive-only sockets that never call `send()` are not currently captured; trigger a no-op send from the page (or wait for the page to send a heartbeat / subscription frame) before subscribing.\n\nSkills cannot supply an arbitrary URL, cannot supply page-context code (the `filter` selector is a declarative JSON object — `parseAs`, `where`, `project` — and the realm rejects functions or strings of JS at the boundary), and cannot intercept outbound `send` traffic. Subscribers owned by a scoop auto-close when the scoop is dropped.\n\n### `sliccy:http` — standard API-client builder\n\n`require('sliccy:http')` exposes `http.client({ baseUrl, token, headers, retry, timeoutMs })`. Standardizes the `build URL → merge headers → resolve auth → fetch → unwrap JSON → throw on !ok` boilerplate. `token` is **lazy** — resolved freshly per request so token rotation / refresh hooks are picked up without recreating the client. Backoff is exponential, but **`Retry-After` (when present and parseable, in seconds or HTTP date) takes precedence** — the server knows its own rate limit.\n\n```typescript\nconst http = require('sliccy:http');\nhttp.client(config: {\n  baseUrl?: string;\n  token?: (req?: { method: string; path: string; url: string }) => string | Promise<string | null | undefined>;\n  headers?: Record<string, string>;\n  retry?: { on: number[]; maxAttempts: number };  // maxAttempts is total (including first)\n  timeoutMs?: number;                              // per-attempt timeout; aborts the fetch\n}): {\n  get(path, opts?):    Promise<unknown>;\n  post(path, opts?):   Promise<unknown>;\n  put(path, opts?):    Promise<unknown>;\n  patch(path, opts?):  Promise<unknown>;\n  delete(path, opts?): Promise<unknown>;\n}\n// opts: { params?, headers?, body?, signal?: AbortSignal, raw?: boolean }\n//  - body object → JSON, params → querystring\n//  - signal: caller-owned abort signal (timeoutMs creates its own per-attempt signal that combines with this)\n//  - raw: when true, returns { body, headers, status } instead of just body — needed for pagination (Link header) and rate-limit (X-RateLimit-*) instrumentation\n```\n\n```javascript\nconst http = require('sliccy:http');\nconst skill = require('sliccy:skill');\nconst api = http.client({\n  baseUrl: 'https://graph.microsoft.com/v1.0',\n  token: () => skill.token('microsoft'),\n  headers: { Accept: 'application/json' },\n  retry: { on: [429, 503], maxAttempts: 4 },\n});\n\nconst me = await api.get('/me');\nconst sent = await api.post('/me/sendMail', {\n  body: {\n    message: {/* … */},\n  },\n});\n// Non-2xx throws `HttpError` with { status, statusText, url, body }.\n```\n\n```javascript\n// raw responses for pagination\nconst resp = await api.get('/users', { raw: true });\nconst link = resp.headers['link']; // e.g. '<…/users?page=2>; rel=\"next\"'\n\n// per-request abort\nconst ctl = new AbortController();\nsetTimeout(() => ctl.abort(), 5000);\nawait api.get('/slow', { signal: ctl.signal });\n\n// token with request context (e.g. different token for reads vs writes)\nconst api = http.client({\n  baseUrl: 'https://api.example.com',\n  token: (req) => (req?.method === 'GET' ? skill.token('read') : skill.token('write')),\n});\n```\n\n### `sliccy:hid` / `sliccy:serial` / `sliccy:usb` — native device scripting\n\n`require('sliccy:hid')` / `require('sliccy:serial')` / `require('sliccy:usb')` expose the WebHID / Web Serial / WebUSB bridges. The top-level entry points are `hid.list()` / `hid.request(filters?)` (and parity `serial.*` / `usb.*`); each device returned carries its opaque handle and methods that round-trip via panel-RPC. The handle namespace is shared with the `hid` / `serial` / `usb` shell commands — a port from `serial request` is reachable as `(await serial.list()).find(p => p.handle === 'serial1')`. Chromium-only; unavailable in the cloud / hosted-leader float. `hid.request()` still needs a user gesture (same as the shell `hid request`).\n\nHID devices expose an `EventTarget`-shaped surface so a VIA-style **request/response in one script** doesn't race: subscribe `'inputreport'` first, then `sendReport`, await the callback. The first listener lazily subscribes the kernel-side relay; the last `removeEventListener` (or realm teardown) unsubscribes — no leaked page-side listeners.\n\n```typescript\nconst hid = require('sliccy:hid');\nhid.list(): Promise<HidDevice[]>\nhid.request(filters?: HidDeviceFilter | HidDeviceFilter[]): Promise<HidDevice>\n\n// On each HidDevice (carries `handle`, `vendorId`, `productId`, `productName`, `collections`):\ndevice.open(): Promise<void>\ndevice.close(): Promise<void>\ndevice.sendReport(reportId: number, data: ArrayBuffer | ArrayBufferView): Promise<void>\ndevice.sendFeatureReport(reportId: number, data: ArrayBuffer | ArrayBufferView): Promise<void>\ndevice.receiveFeatureReport(reportId: number): Promise<DataView>\ndevice.addEventListener('inputreport', cb): void   // event: { reportId, data: DataView }\ndevice.removeEventListener('inputreport', cb): void\ndevice.addEventListener('disconnect', cb): void    // registers; no backend emit yet\ndevice.onInputReport(cb): void                     // alias for addEventListener('inputreport', cb)\n```\n\n```javascript\n// VIA-style protocol-version round-trip as a single .jsh script.\n// Subscribe BEFORE sendReport so the reply can't beat the listener.\nconst hid = require('sliccy:hid');\nconst [device] = await hid.list();\nawait device.open();\nconst reply = new Promise((resolve, reject) => {\n  const t = setTimeout(() => reject(new Error('timeout')), 1000);\n  device.addEventListener('inputreport', function once(e) {\n    clearTimeout(t);\n    device.removeEventListener('inputreport', once);\n    resolve(new Uint8Array(e.data.buffer, e.data.byteOffset, e.data.byteLength));\n  });\n});\nawait device.sendReport(0, new Uint8Array([0x01]));\nconst bytes = await reply;\nconsole.log([...bytes].map((b) => b.toString(16).padStart(2, '0')).join(' '));\n```\n\n`serial.*` mirrors the shell surface (`open` / `close` / `read` / `write` / `getSignals` / `setSignals` on serial ports). **`usb.*` does not** — USB device methods carry their **WebUSB** names, not the `usb` shell command's verbs:\n\n```typescript\ndevice.open(): Promise<void>\ndevice.close(): Promise<void>\ndevice.reset(): Promise<void>\ndevice.selectConfiguration(configurationValue: number): Promise<void>\ndevice.claimInterface(interfaceNumber: number): Promise<void>\ndevice.releaseInterface(interfaceNumber: number): Promise<void>\ndevice.controlTransferIn(setup, length): Promise<{ status: string; data: DataView }>\ndevice.controlTransferOut(setup, data): Promise<{ status: string; bytesWritten: number }>\ndevice.transferIn(endpointNumber: number, length: number): Promise<{ status: string; data: DataView }>\ndevice.transferOut(endpointNumber: number, data): Promise<{ status: string; bytesWritten: number }>\ndevice.clearHalt(direction: 'in' | 'out', endpointNumber: number): Promise<void>\n```\n\nSo it is `claimInterface(1)`, not `claim(1)`; `controlTransferIn(...)`, not `controlIn(...)`. Note the read results resolve `{ status, data }` where `data` is a **`DataView`** — wrap it (`new Uint8Array(d.data.buffer, d.data.byteOffset, d.data.byteLength)`) before treating it as bytes.\n\n`clearHalt` recovers a single stalled bulk/interrupt endpoint. Prefer it to\n`reset()`, which re-enumerates the whole device and drops any claim another\nclient (a host `adb` server, say) holds on it.\n\nEach device also carries its **configuration descriptors** as plain data, so an\ninterface can be located by class/subclass/protocol without opening the device\nand re-reading the descriptor over a control transfer:\n\n```typescript\ndevice.configurations?: Array<{\n  configurationValue: number;\n  configurationName?: string;\n  interfaces: Array<{\n    interfaceNumber: number;\n    claimed: boolean;\n    alternates: Array<{\n      alternateSetting: number;\n      interfaceClass: number;\n      interfaceSubclass: number;\n      interfaceProtocol: number;\n      interfaceName?: string;\n      endpoints: Array<{\n        endpointNumber: number;\n        direction: 'in' | 'out';\n        type: 'bulk' | 'interrupt' | 'isochronous';\n        packetSize: number;\n      }>;\n    }>;\n  }>;\n}>\n```\n\nIt is **optional** — absent when the platform does not expose the tree — so\nbranch on it. Endpoints reported with a direction or type outside the vocabulary\nabove are omitted rather than passed through, so matching on those fields is\nsafe.\n\nNeither `serial.*` nor `usb.*` carries the `EventTarget` shape — those transports are explicit-poll.\n\nFor ESP32 / ESP8266 work, drive `esptool` through `require('sliccy:exec')` (there is no bare `exec` global). Beyond the existing `chip_id` / `read_mac` / `erase_flash` / `write_flash` verbs, the read/inspect set is now `flash_id`, `read_reg <addr>`, `read_flash <addr> <size> <outfile>`, `erase_region <addr> <size>`, and `run`. Pass `--port <handle>` to reuse a port from `serial request` so no second picker fires:\n\n```javascript\nconst serial = require('sliccy:serial');\nconst { exec } = require('sliccy:exec');\nconst port = (await serial.list())[0] ?? (await serial.request());\nconst { stdout } = await exec(`esptool --port ${port.handle} flash_id`);\nconsole.log(stdout);\nawait exec.spawn([\n  'esptool',\n  '--port',\n  port.handle,\n  'read_flash',\n  '0',\n  '0x1000',\n  `${process.env.TMPDIR ?? '/tmp'}/header.bin`,\n]);\n```\n\n## Reaching these from sprinkles & dips\n\nThe high-value capabilities here — `exec` / `exec.spawn`, `fetch`, `http.client`, `browser.*`, and the device APIs (`hid.*` / `serial.*` / `usb.*`) — are also exposed to `.shtml` **sprinkles** and **trusted dips** through the `slicc.*` bridge, which routes each call into the **same worker shell** `.jsh` scripts run in. So a sprinkle button can `await slicc.exec('…')` to reach any supplemental command or `.jsh` script, `await slicc.agent('…')` to spawn a one-shot sub-scoop, or `slicc.hid.on('inputreport', cb)` + `slicc.hid.sendReport(handle, reportId, bytes)` to drive a VIA-style keyboard from a UI panel (handles persist across button clicks). The bridge is trust-gated: VFS-sourced sprinkles and trusted dips get it; untrusted inline-chat dips never receive `exec` / `agent` / `browser` / device globals. See the sprinkles skill (`/workspace/skills/sprinkles/SKILL.md`) \"Shell, agent, and jsh globals\" section, and `docs/shell-reference.md` \"Sprinkle & Dip Bridge\" (developer-facing).\n";export{e as default};
+var e="# jsh runtime extensions\n\nThis file is bundled into the agent VFS at `/workspace/skills/skill-authoring/jsh-runtime-extensions.md`. Developer-facing equivalent: `docs/shell-reference.md` (which lives outside the VFS). Keep both in sync when the runtime surface changes.\n\n## Runtime globals (Globals API)\n\nEvery `.jsh` script runs in an async wrapper with a small Node-standard surface available as bare globals. SLICC's capability bridges (exec, agent, http, browser, USB / Serial / HID, skill, color, cli, time, fmt, pool) are NOT bare globals; they are reached via the `sliccy:` virtual-module scheme below.\n\n### Node-standard bare globals\n\n| Global                                                           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |\n| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `process`                                                        | `argv` (with `.parseFlags()`), `env`, `cwd()`, `exit(code)`, `stdout.write`, `stderr.write`. `stdin` is a fully-buffered (no streaming) one-shot value with three surfaces sharing one `consumed` flag — `read()` (returns `null` when nothing was piped, Node parity), events (`on('data')`→`'end'`→`'close'`, single chunk, no real streaming — `pause()` suppresses emission until `resume()`, and `exit(N)` from a handler exits with code `N`), and async iterator. Drain via exactly one; the others then see EOF. |\n| `console`                                                        | `log`/`info`/`debug`/`dirxml`/`table`/`dir` → stdout; `warn`/`error`/`assert`/`trace` → stderr (`assert` does not throw). `group`/`groupCollapsed`/`groupEnd` indent; `time`/`timeEnd`/`timeLog` and `count`/`countReset` are labeled; `clear` is a no-op. All 19 standard methods are functions.                                                                                                                                                                                                                        |\n| `fetch`                                                          | Standard `fetch` routed through SLICC's proxied transport (cookies + CORS + secret masking handled). Binary bodies (`Uint8Array` / `Blob` / `FormData`) are sent as raw bytes — bytes ≥0x80 are not UTF-8-expanded. `await res.json()` / `res.text()` resolve from the already-buffered body and keep the realm alive for the rest of the continuation.                                                                                                                                                                  |\n| `require(p)`                                                     | Synchronous CJS `require`. Use `require('sliccy:<name>')` for capability bridges, `require('fs')` / `require('node:fs')` for the VFS bridge, `require('<pkg>')` for installed packages.                                                                                                                                                                                                                                                                                                                                  |\n| `Buffer` / `globalThis`                                          | Node-standard surface.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `setTimeout` / `clearTimeout` / `setInterval` / `queueMicrotask` | Web timer surface (also reachable through `globalThis`). Outstanding timeouts and intervals keep the realm alive the way Node keeps a process alive for ref'd handles; `queueMicrotask` is not a handle. `process.exit()` cancels pending timers.                                                                                                                                                                                                                                                                        |\n| `__dirname` / `__filename`                                       | CJS scope vars — the running script's own directory and absolute path.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |\n| `module` / `exports`                                             | CJS module record (writeable; useful when a `.jsh` is treated as a library by a sibling `require('./helper.jsh')`).                                                                                                                                                                                                                                                                                                                                                                                                      |\n| `process.argv.parseFlags()`                                      | Parse `--flag=val` / `--flag val` / `-x` / positional / `--` passthrough into `{ positional, flags, subcommand, passthrough }`.                                                                                                                                                                                                                                                                                                                                                                                          |\n\n### Capability bridges — `sliccy:` virtual modules\n\nThe bespoke globals are hard-cut. Reach each capability via `require('sliccy:<name>')` (CJS) or `import ... from 'sliccy:<name>'` (ESM). `require('fs')` / `require('node:fs')` keeps returning the VFS bridge.\n\n| `require('sliccy:<name>')`                    | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                    |\n| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `sliccy:exec`                                 | Callable `exec(cmd)` plus `.spawn(argv[])`, `.start(cmdOrArgv, opts?)` (killable, buffered-stdin spawn handle) and `.exec` self-reference. Returns `{ stdout, stderr, exitCode }`. Use `const { exec } = require('sliccy:exec')` or `const exec = require('sliccy:exec')`.                                                                                                                                                 |\n| `sliccy:agent`                                | Callable `agent(prompt, opts?)` — spawns a one-shot sub-scoop, feeds it the prompt, blocks until the agent loop completes; resolves to trimmed final text (JSON-parsed when `opts.schema` is set), REJECTS on non-zero exit or schema-parse failure. `.spawn(prompt, opts?)` is the non-throwing variant → `{ finalText, exitCode, stderr }`. `opts`: `model`, `thinking`, `cwd`, `allowedCommands`, `readOnly`, `schema`. |\n| `sliccy:skill`                                | Frozen `{ dir, root, refs, assets, config(), config(updates), token(providerId) }`. `refs`/`assets` resolve from the skill root (parent of `scripts/` when the script lives there). Replaces ad-hoc `argv[1]` dirname math and `oauth-token` shell-outs.                                                                                                                                                                   |\n| `sliccy:http`                                 | `http.client({ baseUrl, token, headers, retry, timeoutMs })` builder.                                                                                                                                                                                                                                                                                                                                                      |\n| `sliccy:browser`                              | `findTab`, `ensureTab`, `eval`, `evalAsync`, `cookie`, `localStorage`, `fetch`, `websocket.on(...).filter(...).forward(...)`.                                                                                                                                                                                                                                                                                              |\n| `sliccy:usb` / `sliccy:serial` / `sliccy:hid` | `list()` / `request()` + device methods (`open`/`close`/`sendReport`/...). Chromium-only.                                                                                                                                                                                                                                                                                                                                  |\n| `sliccy:cli`                                  | `die(msg, opts?)`, `out(value)`, `warn(msg, opts?)`, `help(text)`. `opts` is `number` or `{ exitCode?, prefix? }`; `prefix: ''` removes the default `Error:` / `Warning:` label entirely.                                                                                                                                                                                                                                  |\n| `sliccy:color`                                | ANSI helpers: `green`, `red`, `yellow`, `gray`, `bold`, `cyan`, `dim`, plus `enabled` flag (auto-disabled on non-TTY / `NO_COLOR`).                                                                                                                                                                                                                                                                                        |\n| `sliccy:time`                                 | `parseDuration(spec)`, `ago(spec)`, `range(spec)`, `future(spec)`, `gmailDate(spec)`. Units: `ms s m h d w M y` (note: `m` = minutes, `M` = months).                                                                                                                                                                                                                                                                       |\n| `sliccy:fmt`                                  | `trunc(s, n)`, `col(s, width)`, `table(rows, widths?)`, `date(value, style?)`. `style`: `'short' \\| 'iso' \\| 'human' \\| 'locale'` (locale = `Intl.DateTimeFormat` medium).                                                                                                                                                                                                                                                 |\n| `sliccy:pool`                                 | `pool(n, items, fn)` — bounded concurrency runner, results returned in input order.                                                                                                                                                                                                                                                                                                                                        |\n\n`require('sliccy:<unknown>')` throws a scheme-specific error (`Unknown sliccy: module '<name>'`); empty `require('sliccy:')` throws `empty sliccy: module name`. `sliccy:` lookups never hit the registry / `node_modules` / `ipk install`.\n\n### Filesystem (VFS bridge)\n\n`require('fs')` and `require('node:fs')` return the VFS bridge (`readFile`, `writeFile`, `readFileBinary`, `writeFileBinary`, `readDir`, `exists`, `stat`, `mkdir`, `rm`, `fetchToFile(url, path)`), plus the sync set (`readFileSync`, `writeFileSync`, `existsSync`, `statSync`, …). All paths are VFS-resolved. There is no bare `fs` global.\n\nStdio fds and device paths work like Node: `fs.readFileSync(0, 'utf8')` (or `'/dev/stdin'`) reads the full piped stdin without consuming `process.stdin`; `fs.writeFileSync(1, …)` / `fs.writeFileSync(2, …)` (or `/dev/stdout` / `/dev/stderr`) write to stdout/stderr; `existsSync`/`statSync` report the three stream devices as present. Unknown numeric fds and wrong-direction stream ops throw `EBADF`.\n\n### Line reading (`readline`)\n\n`require('readline')` and `require('readline/promises')` work over the buffered stdin:\n\n```javascript\nconst readline = require('readline/promises');\nconst rl = readline.createInterface({ input: process.stdin, output: process.stdout });\nfor await (const line of rl) console.log('>', line);\n// or: rl.on('line', fn) … rl.on('close', fn), or const answer = await rl.question('name? ')\n```\n\nCreating the interface drains `process.stdin` (one-shot, like Node's flowing mode); `question()` answers with the next unconsumed line (`''` at EOF).\n\n### Examples for the non-trivial globals\n\n```javascript\n// process.argv.parseFlags() — replace per-skill arg loops\nconst { positional, flags, subcommand, passthrough } = process.argv.parseFlags();\n// e.g. `mycli send --to alice --json -- --raw` →\n//   positional: ['send', 'alice'], flags: { to: 'alice', json: true },\n//   subcommand: 'send', passthrough: ['--raw']\n```\n\n**Two-level routing**: `parseFlags` populates `subcommand` only from the first positional. For `<cmd> <sub> [args]` CLIs, route the second level manually from `positional[1]`:\n\n```javascript\nconst { positional, flags } = process.argv.parseFlags();\nconst [cmd, sub] = positional;\nswitch (cmd) {\n  case 'pr':\n    if (sub === 'list') return prList(flags);\n    if (sub === 'view') return prView(positional[2], flags);\n    return cli.die(`unknown pr subcommand: ${sub}`);\n  // …\n}\n```\n\n```javascript\n// cli + color — early-exit helpers and color (both via sliccy:)\nconst cli = require('sliccy:cli');\nconst c = require('sliccy:color');\nif (!flags.to) cli.die('--to is required'); // writes \"Error: …\" to stderr, exits 1\ncli.out({ ok: true }); // pretty-prints JSON to stdout with trailing newline\nconsole.log(c.green('✓'), c.dim('done'));\n```\n\n```javascript\n// domain-specific prefix instead of the default \"Error:\"\nconst cli = require('sliccy:cli');\nif (!flags.repo) cli.die('--repo is required', { prefix: 'gh' });\n// → \"gh: --repo is required\"\ncli.warn('rate limit at 80%', { prefix: 'gh' });\n```\n\n```javascript\n// time — duration math\nconst time = require('sliccy:time');\nconst since = time.ago('7d'); // Date 7 days ago\nconst q = `after:${time.gmailDate('7d')}`; // \"after:2026/05/22\"\n\n// fmt — ANSI-aware table\nconst fmt = require('sliccy:fmt');\nconst c = require('sliccy:color');\nconsole.log(\n  fmt.table([\n    ['name', 'status'],\n    ['hub', c.green('up')],\n    ['relay', c.red('down')],\n  ])\n);\n\n// pool — bounded concurrency\nconst pool = require('sliccy:pool');\nconst results = await pool(4, urls, async (url) => (await fetch(url)).status);\n```\n\n```javascript\n// exec.spawn(argv[]) — bypass shell parsing. Use for any arg derived from\n// untrusted input: it can't be shell-interpolated.\nconst { exec } = require('sliccy:exec');\nconst userMessage = flags.message ?? 'wip';\nawait exec.spawn(['git', 'commit', '-m', userMessage]); // safe even with quotes/spaces in userMessage\n```\n\n```javascript\n// exec.start(cmdOrArgv, opts?) — killable, buffered-stdin spawn handle. Buffer\n// stdin with .write(), launch with .end(), await .done for the result, and\n// .kill(signal?) to abort. NOT interactive/streaming — just-bash is one-shot\n// buffered, so stdin is a single upfront buffer and post-launch writes drop.\nconst { exec } = require('sliccy:exec');\nconst h = exec.start(['jq', '.name']);\nh.stdin.write('{\"name\":\"slicc\"}');\nh.stdin.end();\nconst { stdout, exitCode } = await h.done;\n// h.kill('SIGTERM') fans a signal out via the exec:kill op.\n```\n\n```javascript\n// agent — spawn a one-shot sub-scoop and block on its result. The callable\n// resolves to the sub-scoop's final text; with `schema` it resolves to the\n// parsed object (rejects if the reply wasn't valid JSON) and rejects on a\n// non-zero exit. Use agent.spawn(...) when you want the raw outcome instead.\nconst agent = require('sliccy:agent');\nconst summary = await agent('Summarize /workspace/README.md in one line', {\n  thinking: 'low',\n  readOnly: '/workspace/',\n});\n\nconst parsed = await agent('Extract the title as {\"title\": string}', {\n  schema: { type: 'object', properties: { title: { type: 'string' } } },\n});\n\nconst { finalText, exitCode, stderr } = await agent.spawn('do the thing', {\n  model: 'claude-opus-4-6',\n  cwd: process.env.TMPDIR ?? '/tmp',\n  allowedCommands: 'git,node',\n});\n```\n\n### `require('child_process')` — Node process API over the exec bridge\n\n`require('child_process')` / `require('node:child_process')` resolves in the `.jsh` / `node` realm to a shim built on `exec.start`. `exec` / `execFile` / `spawn` map onto the one-shot just-bash exec pipeline: the returned `ChildProcess` is an `EventEmitter` that fires `'exit'` / `'close'`, and its `.stdout` / `.stderr` are Readable stubs that each emit a single `'data'` chunk then `'end'`. `exec` / `execFile` also carry a `util.promisify.custom` implementation resolving `{ stdout, stderr }`.\n\n```javascript\nconst { exec } = require('child_process');\nconst { promisify } = require('util');\nconst { stdout } = await promisify(exec)('ls -la /workspace');\n```\n\nThe **sync forms** (`execSync` / `spawnSync` / `execFileSync`) and `fork` throw — just-bash has no synchronous or long-lived process model. `.bsh` scripts (which run in the target page via CDP, not the realm) have no shell bridge at all, so `require('child_process')` there is unavailable; use `exec()` from a `.jsh` script instead.\n\n## jsh runtime extensions\n\nThe following capabilities collapse the boilerplate that 18 of 23 surveyed skills reinvented. They're available in both standalone and extension floats; each is reached through `require('sliccy:<name>')` (or the equivalent ESM `import`).\n\n### `sliccy:skill` — skill-root paths, config, tokens\n\nComputed once at boot from `argv[1]` and frozen. Replaces ad-hoc `process.argv[1].substring(0, …)` dirname math, bespoke `.config` JSON readers, and `oauth-token` shell-outs.\n\nAgent Skills layout is `<skill-root>/{SKILL.md,scripts/,references/,assets/}`. `skill.dir` is the directory containing the running script. When any path segment of that directory is `scripts` (`<skill-root>/scripts/<name>.jsh`, including helpers under `scripts/<subdir>/`), `skill.root` is the parent of that segment — the skill folder. Otherwise `skill.root` equals `skill.dir`. `skill.refs` and `skill.assets` resolve from `skill.root`. `skill.config()` still reads/writes `<dir>/.config` (typically `scripts/.config`) so `upskill` can preserve that dotfile.\n\n```typescript\nconst skill = require('sliccy:skill');\nskill.dir: string                                              // directory containing the running script\nskill.root: string                                             // skill folder (parent of `scripts/` when applicable)\nskill.refs: string                                             // `<root>/references`\nskill.assets: string                                           // `<root>/assets`\nskill.config(): Promise<Record<string, unknown> | null>        // read parsed JSON from `<dir>/.config`\nskill.config(updates): Promise<Record<string, unknown>>        // shallow-merge + write, returns merged\nskill.token(providerId: string): Promise<string>               // shells out to `oauth-token <id>`\n```\n\n```javascript\nconst skill = require('sliccy:skill');\nconst fs = require('fs');\nconst cfg = (await skill.config()) ?? {};\nconst token = await skill.token('adobe');\nconst tmpl = await fs.readFile(`${skill.refs}/prompt.md`);\n```\n\n### `sliccy:browser` — page-context CDP bridge\n\nReplaces the `exec('playwright-cli tab-list')` shell-out + regex parse used in ~12 skills. Accepts a `TabHandle` (from `findTab` / `ensureTab`) or a bare `targetId` string. `eval` / `evalAsync` serialize functions to a string call expression so realm code can pass a closure as ergonomically as a string.\n\n```typescript\nconst browser = require('sliccy:browser');\nbrowser.findTab(opts: { domain?: string; urlMatch?: RegExp | string }): Promise<TabHandle | null>\nbrowser.ensureTab(url: string, opts?: { matchUrl?: RegExp | string }): Promise<TabHandle>\nbrowser.eval(tab, fn: Function | string): Promise<unknown>      // sync expression\nbrowser.evalAsync(tab, fn: AsyncFunction): Promise<unknown>     // async, returns parsed JSON\nbrowser.cookie(tab, name: string): Promise<string | null>\nbrowser.localStorage(tab, key: string): Promise<string | null>\n```\n\n```javascript\nconst browser = require('sliccy:browser');\nconst cli = require('sliccy:cli');\nconst tab = await browser.findTab({ domain: 'slack.com' });\nif (!tab) cli.die('open slack.com first');\nconst team = await browser.eval(tab, () => document.title);\nconst xoxc = await browser.localStorage(tab, 'localConfig_v2');\n```\n\n### `browser.fetch(tab, url, opts)` — page-context fetch\n\nReplaces the eval-file + base64 + double-JSON-unwrap pattern in ~9 skills. Runs inside the tab's origin, so **session cookies and same-origin headers are automatic** — don't try to forward cookies manually.\n\n```typescript\nbrowser.fetch(tab: TabHandle | string, url: string, opts?: {\n  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | ...;\n  headers?: Record<string, string>;\n  body?: unknown;                   // object → JSON-stringified\n  credentials?: 'include' | 'omit'; // defaults to 'include'\n  responseType?: 'text' | 'json' | 'binary';\n  timeoutMs?: number;               // page-side AbortSignal.timeout()\n}): Promise<{\n  ok: boolean; status: number; statusText: string;\n  url: string; redirected: boolean; // final URL after redirects\n  headers: Record<string, string>;\n  body: unknown; bodyEncoding?: 'base64';\n}>\n```\n\nFrom the shell, `curlwright` is the same capability with curl's flags — reach for it while\nexploring an API, and for `browser.fetch` once the call is settled into a `.jsh`.\n\n```javascript\nconst browser = require('sliccy:browser');\nconst cli = require('sliccy:cli');\nconst resp = await browser.fetch(tab, '/api/conversations.list', {\n  method: 'POST',\n  body: { limit: 100 },\n});\nif (!resp.ok) cli.die(`slack ${resp.status}`);\nconst channels = resp.body.channels;\n```\n\n### `browser.websocket` — declarative WebSocket observer\n\nSanctioned replacement for `WebSocket.prototype.send` monkey-patches. **REQUIRED for any new WS-watch use case** — skill code MUST NOT author page-context functions that patch a third-party page's prototypes or see the inbound frame firehose.\n\n```typescript\nconst sub = await browser.websocket\n  .on(tab, { urlMatch: /wss-primary\\.slack\\.com/ })\n  .filter({ parseAs: 'json', where: { type: 'message', channel: 'C0899S7HV0E' } })\n  .forward({ sink: 'webhook', webhookId: 'slack-watch-abc123' });\n\nawait sub.update({ filter: { where: { channel: 'C-new' } } });\nawait sub.close();\nawait browser.websocket.list();\n```\n\n**Sink set is a closed enum.** The page-side router (runtime-owned, audited once) only knows how to forward matched frames to:\n\n- `'webhook'` — resolved against the existing `webhook` registry; an unknown `webhookId` rejects at subscriber-creation time.\n- `'scoop'` — delivered via the orchestrator's scoop dispatch.\n- `'vfs'` — appended to an absolute path that must start with `/workspace/`.\n- `'log'` — telemetry only.\n\n**Discovery requires outbound `send()`.** The router patches `WebSocket.prototype.send` as a pure discovery hook — it never observes outbound frames, but a WebSocket instance is only wrapped (and its inbound `message` listener attached) the first time something calls `send()` on it. Receive-only sockets that never call `send()` are not currently captured; trigger a no-op send from the page (or wait for the page to send a heartbeat / subscription frame) before subscribing.\n\nSkills cannot supply an arbitrary URL, cannot supply page-context code (the `filter` selector is a declarative JSON object — `parseAs`, `where`, `project` — and the realm rejects functions or strings of JS at the boundary), and cannot intercept outbound `send` traffic. Subscribers owned by a scoop auto-close when the scoop is dropped.\n\n### `sliccy:http` — standard API-client builder\n\n`require('sliccy:http')` exposes `http.client({ baseUrl, token, headers, retry, timeoutMs })`. Standardizes the `build URL → merge headers → resolve auth → fetch → unwrap JSON → throw on !ok` boilerplate. `token` is **lazy** — resolved freshly per request so token rotation / refresh hooks are picked up without recreating the client. Backoff is exponential, but **`Retry-After` (when present and parseable, in seconds or HTTP date) takes precedence** — the server knows its own rate limit.\n\n```typescript\nconst http = require('sliccy:http');\nhttp.client(config: {\n  baseUrl?: string;\n  token?: (req?: { method: string; path: string; url: string }) => string | Promise<string | null | undefined>;\n  headers?: Record<string, string>;\n  retry?: { on: number[]; maxAttempts: number };  // maxAttempts is total (including first)\n  timeoutMs?: number;                              // per-attempt timeout; aborts the fetch\n}): {\n  get(path, opts?):    Promise<unknown>;\n  post(path, opts?):   Promise<unknown>;\n  put(path, opts?):    Promise<unknown>;\n  patch(path, opts?):  Promise<unknown>;\n  delete(path, opts?): Promise<unknown>;\n}\n// opts: { params?, headers?, body?, signal?: AbortSignal, raw?: boolean }\n//  - body object → JSON, params → querystring\n//  - signal: caller-owned abort signal (timeoutMs creates its own per-attempt signal that combines with this)\n//  - raw: when true, returns { body, headers, status } instead of just body — needed for pagination (Link header) and rate-limit (X-RateLimit-*) instrumentation\n```\n\n```javascript\nconst http = require('sliccy:http');\nconst skill = require('sliccy:skill');\nconst api = http.client({\n  baseUrl: 'https://graph.microsoft.com/v1.0',\n  token: () => skill.token('microsoft'),\n  headers: { Accept: 'application/json' },\n  retry: { on: [429, 503], maxAttempts: 4 },\n});\n\nconst me = await api.get('/me');\nconst sent = await api.post('/me/sendMail', {\n  body: {\n    message: {/* … */},\n  },\n});\n// Non-2xx throws `HttpError` with { status, statusText, url, body }.\n```\n\n```javascript\n// raw responses for pagination\nconst resp = await api.get('/users', { raw: true });\nconst link = resp.headers['link']; // e.g. '<…/users?page=2>; rel=\"next\"'\n\n// per-request abort\nconst ctl = new AbortController();\nsetTimeout(() => ctl.abort(), 5000);\nawait api.get('/slow', { signal: ctl.signal });\n\n// token with request context (e.g. different token for reads vs writes)\nconst api = http.client({\n  baseUrl: 'https://api.example.com',\n  token: (req) => (req?.method === 'GET' ? skill.token('read') : skill.token('write')),\n});\n```\n\n### `sliccy:hid` / `sliccy:serial` / `sliccy:usb` — native device scripting\n\n`require('sliccy:hid')` / `require('sliccy:serial')` / `require('sliccy:usb')` expose the WebHID / Web Serial / WebUSB bridges. The top-level entry points are `hid.list()` / `hid.request(filters?)` (and parity `serial.*` / `usb.*`); each device returned carries its opaque handle and methods that round-trip via panel-RPC. The handle namespace is shared with the `hid` / `serial` / `usb` shell commands — a port from `serial request` is reachable as `(await serial.list()).find(p => p.handle === 'serial1')`. Chromium-only; unavailable in the cloud / hosted-leader float. `hid.request()` still needs a user gesture (same as the shell `hid request`).\n\nHID devices expose an `EventTarget`-shaped surface so a VIA-style **request/response in one script** doesn't race: subscribe `'inputreport'` first, then `sendReport`, await the callback. The first listener lazily subscribes the kernel-side relay; the last `removeEventListener` (or realm teardown) unsubscribes — no leaked page-side listeners.\n\n```typescript\nconst hid = require('sliccy:hid');\nhid.list(): Promise<HidDevice[]>\nhid.request(filters?: HidDeviceFilter | HidDeviceFilter[]): Promise<HidDevice>\n\n// On each HidDevice (carries `handle`, `vendorId`, `productId`, `productName`, `collections`):\ndevice.open(): Promise<void>\ndevice.close(): Promise<void>\ndevice.sendReport(reportId: number, data: ArrayBuffer | ArrayBufferView): Promise<void>\ndevice.sendFeatureReport(reportId: number, data: ArrayBuffer | ArrayBufferView): Promise<void>\ndevice.receiveFeatureReport(reportId: number): Promise<DataView>\ndevice.addEventListener('inputreport', cb): void   // event: { reportId, data: DataView }\ndevice.removeEventListener('inputreport', cb): void\ndevice.addEventListener('disconnect', cb): void    // registers; no backend emit yet\ndevice.onInputReport(cb): void                     // alias for addEventListener('inputreport', cb)\n```\n\n```javascript\n// VIA-style protocol-version round-trip as a single .jsh script.\n// Subscribe BEFORE sendReport so the reply can't beat the listener.\nconst hid = require('sliccy:hid');\nconst [device] = await hid.list();\nawait device.open();\nconst reply = new Promise((resolve, reject) => {\n  const t = setTimeout(() => reject(new Error('timeout')), 1000);\n  device.addEventListener('inputreport', function once(e) {\n    clearTimeout(t);\n    device.removeEventListener('inputreport', once);\n    resolve(new Uint8Array(e.data.buffer, e.data.byteOffset, e.data.byteLength));\n  });\n});\nawait device.sendReport(0, new Uint8Array([0x01]));\nconst bytes = await reply;\nconsole.log([...bytes].map((b) => b.toString(16).padStart(2, '0')).join(' '));\n```\n\n`serial.*` mirrors the shell surface (`open` / `close` / `read` / `write` / `getSignals` / `setSignals` on serial ports). **`usb.*` does not** — USB device methods carry their **WebUSB** names, not the `usb` shell command's verbs:\n\n```typescript\ndevice.open(): Promise<void>\ndevice.close(): Promise<void>\ndevice.reset(): Promise<void>\ndevice.selectConfiguration(configurationValue: number): Promise<void>\ndevice.claimInterface(interfaceNumber: number): Promise<void>\ndevice.releaseInterface(interfaceNumber: number): Promise<void>\ndevice.controlTransferIn(setup, length): Promise<{ status: string; data: DataView }>\ndevice.controlTransferOut(setup, data): Promise<{ status: string; bytesWritten: number }>\ndevice.transferIn(endpointNumber: number, length: number): Promise<{ status: string; data: DataView }>\ndevice.transferOut(endpointNumber: number, data): Promise<{ status: string; bytesWritten: number }>\ndevice.clearHalt(direction: 'in' | 'out', endpointNumber: number): Promise<void>\n```\n\nSo it is `claimInterface(1)`, not `claim(1)`; `controlTransferIn(...)`, not `controlIn(...)`. Note the read results resolve `{ status, data }` where `data` is a **`DataView`** — wrap it (`new Uint8Array(d.data.buffer, d.data.byteOffset, d.data.byteLength)`) before treating it as bytes.\n\n`clearHalt` recovers a single stalled bulk/interrupt endpoint. Prefer it to\n`reset()`, which re-enumerates the whole device and drops any claim another\nclient (a host `adb` server, say) holds on it.\n\nEach device also carries its **configuration descriptors** as plain data, so an\ninterface can be located by class/subclass/protocol without opening the device\nand re-reading the descriptor over a control transfer:\n\n```typescript\ndevice.configurations?: Array<{\n  configurationValue: number;\n  configurationName?: string;\n  interfaces: Array<{\n    interfaceNumber: number;\n    claimed: boolean;\n    alternates: Array<{\n      alternateSetting: number;\n      interfaceClass: number;\n      interfaceSubclass: number;\n      interfaceProtocol: number;\n      interfaceName?: string;\n      endpoints: Array<{\n        endpointNumber: number;\n        direction: 'in' | 'out';\n        type: 'bulk' | 'interrupt' | 'isochronous';\n        packetSize: number;\n      }>;\n    }>;\n  }>;\n}>\n```\n\nIt is **optional** — absent when the platform does not expose the tree — so\nbranch on it. Endpoints reported with a direction or type outside the vocabulary\nabove are omitted rather than passed through, so matching on those fields is\nsafe.\n\nNeither `serial.*` nor `usb.*` carries the `EventTarget` shape — those transports are explicit-poll.\n\nFor ESP32 / ESP8266 work, drive `esptool` through `require('sliccy:exec')` (there is no bare `exec` global). Beyond the existing `chip_id` / `read_mac` / `erase_flash` / `write_flash` verbs, the read/inspect set is now `flash_id`, `read_reg <addr>`, `read_flash <addr> <size> <outfile>`, `erase_region <addr> <size>`, and `run`. Pass `--port <handle>` to reuse a port from `serial request` so no second picker fires:\n\n```javascript\nconst serial = require('sliccy:serial');\nconst { exec } = require('sliccy:exec');\nconst port = (await serial.list())[0] ?? (await serial.request());\nconst { stdout } = await exec(`esptool --port ${port.handle} flash_id`);\nconsole.log(stdout);\nawait exec.spawn([\n  'esptool',\n  '--port',\n  port.handle,\n  'read_flash',\n  '0',\n  '0x1000',\n  `${process.env.TMPDIR ?? '/tmp'}/header.bin`,\n]);\n```\n\n## Reaching these from sprinkles & dips\n\nThe high-value capabilities here — `exec` / `exec.spawn`, `fetch`, `http.client`, `browser.*`, and the device APIs (`hid.*` / `serial.*` / `usb.*`) — are also exposed to `.shtml` **sprinkles** and **trusted dips** through the `slicc.*` bridge, which routes each call into the **same worker shell** `.jsh` scripts run in. So a sprinkle button can `await slicc.exec('…')` to reach any supplemental command or `.jsh` script, `await slicc.agent('…')` to spawn a one-shot sub-scoop, or `slicc.hid.on('inputreport', cb)` + `slicc.hid.sendReport(handle, reportId, bytes)` to drive a VIA-style keyboard from a UI panel (handles persist across button clicks). The bridge is trust-gated: VFS-sourced sprinkles and trusted dips get it; untrusted inline-chat dips never receive `exec` / `agent` / `browser` / device globals. See the sprinkles skill (`/workspace/skills/sprinkles/SKILL.md`) \"Shell, agent, and jsh globals\" section, and `docs/shell-reference.md` \"Sprinkle & Dip Bridge\" (developer-facing).\n";export{e as default};