hdms and holesail skills
This commit is contained in:
Raven Scott
+3
-1
@@ -1491,7 +1491,9 @@ var BARE_AGENT_SKILL_SEED_REL = Object.freeze([
|
||||
'skills/.gitkeep',
|
||||
'skills/p2p-os-status/SKILL.md',
|
||||
'skills/bare-os-kernel-proc/SKILL.md',
|
||||
'skills/bare-os-super-developer/SKILL.md'
|
||||
'skills/bare-os-super-developer/SKILL.md',
|
||||
'skills/holesail/SKILL.md',
|
||||
'skills/hdms/SKILL.md'
|
||||
])
|
||||
|
||||
/**
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"schema": 2,
|
||||
"profileId": "bare-os-posix-like",
|
||||
"generatedAt": "2026-04-22T07:14:40.458Z",
|
||||
"generatedAt": "2026-04-22T07:30:25.994Z",
|
||||
"note": "Sparse POSIX Issue 7 coverage hints for /bin utilities. Omitted command names are not yet profiled here.",
|
||||
"commandIndex": [
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"schema": 1,
|
||||
"atMs": 1776842080458,
|
||||
"atMs": 1776843025994,
|
||||
"commands": [
|
||||
"agent",
|
||||
"arch",
|
||||
|
||||
@@ -22,7 +22,7 @@ This tree follows the **agent** Markdown workspace convention: “soul” files
|
||||
3. During a session, the model loads the full document with the **`read_skill`** tool (do not paste huge skills into the user channel unless asked).
|
||||
4. Shared skills can live under **`~/.agent/skills/`**; keep **`workspace/skills/`** for machine-local or repo-specific behavior.
|
||||
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, and **`bare-os-super-developer`** (writing guest scripts/apps and navigating **`ctx`**).
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (Holesail tunnels / initd), and **`hdms`** (Hyperdrive mounts and invite/pair).
|
||||
|
||||
After **`agent --config`** / **`--setup`** (or changing **`owner_name`** / **`agent_label`** via **`edit_agent_config`**), **`IDENTITY.md`** and **`USER.md`** are regenerated from **`config.json`** so the workspace matches the operator and agent label.
|
||||
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: bare-os-hdms
|
||||
version: 1.0.0
|
||||
description: HDMS — extra Hyperdrives under /mnt, registry on the personal drive, Autopass invite/pair, and identity-gated ctx.runHdms.
|
||||
tags: [hdms, hyperdrive, identity, autopass, mounts]
|
||||
requires: [read_man_page, read_file, vfs]
|
||||
---
|
||||
|
||||
# bare-os-hdms Skill
|
||||
|
||||
## When to use
|
||||
|
||||
Use when the user asks about **HDMS** (Hyperdrive Management): **`hdms`** CLI, **`/.bare/hdms/registry.json`**, **`/mnt/<label>`** mounts, **invite/pair** sharing, **`ctx.runHdms`**, **`ctx.bareOsSubscribeHdmsLifecycle`**, or how HDMS relates to **`login`** / guest mode.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **HDMS activates after identity unlock.** Guest sessions can **list** mounts that are already open; **mutating** commands (**`create`**, **`add`**, registry edits, **`invite`**, **`pair`**, etc.) go through **`assertLoggedIn`**: require **`ctx.identity.state === 'unlocked'`** and an active HDMS controller.
|
||||
- Implementation: **`packages/bare-os-booter/lib/hdms-manager.js`** (**`runHdmsCli`**, **`HdmsController`**), exposed as **`ctx.runHdms(argv)`** in **`packages/bare-os-booter/index.js`**.
|
||||
|
||||
## Registry and VFS
|
||||
|
||||
- **Registry path (constant):** **`/.bare/hdms/registry.json`** on the **personal** drive (**`HDMS_REGISTRY_PATH`**).
|
||||
- **Writable mounts:** **`hdms create <label>`** — new Corestore namespace + Hyperdrive, replicate to swarm.
|
||||
- **Read-only by key:** **`hdms add <label> <z32-key>`** — open an existing drive by key string.
|
||||
- **VFS:** paths **`/mnt/<label>/…`**; writable mounts allow **`put`** on those routes.
|
||||
|
||||
## Invite and pair (Autopass / BlindPairing)
|
||||
|
||||
High-level behavior (details and caveats in **`handbook/05-identity-vault-and-hdms.md`**):
|
||||
|
||||
- **Invite with a drive:** **`hdms invite [--read-only] <label>`** stores a pending share for the peer. **`--rw`** uses a separate Autopass key (**`pending-share-rw`**) with **`signerKey`** + **`writerSecretHex`** so peers do not silently mount read-only when read/write was intended. **Anyone who can read the paired Autopass ledger can write the drive** — treat **`--rw`** as highly sensitive.
|
||||
- **`hdms invite --read-only`** on a writable label sets the peer’s Autopass writer row read-only; **read-only Autobase writers are not append-capable**, so **`invite --read-only` + `pair` often fails** with “Not writable” / timeout — for normal HDMS pairing, omit **`--read-only`** unless you understand the limitation.
|
||||
- **Pair:** **`hdms pair [--persist|--no-persist] <invite>`** — bounded waits (**`BARE_OS_HDMS_PAIR_WAIT_MS`**, **`BARE_OS_HDMS_PAIR_READY_MS`**, **`BARE_OS_HDMS_PAIR_SHARE_WAIT_MS`**, **`BARE_OS_HDMS_INVITE_CLEAR_MS`** — see env appendix / booter). Default persists to registry; **`--no-persist`** keeps the mount **ephemeral**. Inviter must stay **online** with matching **Hyperswarm bootstrap** or pairing stalls.
|
||||
- **Invite without a label:** **`hdms invite`** (optional **`--read-only`**) only pairs Autopass; pending drive offers are cleared — **no automatic `/mnt` mount** for the peer.
|
||||
|
||||
## Kernel hooks
|
||||
|
||||
- **`ctx.bareOsSubscribeHdmsLifecycle(fn)`** — callback with **`{ kind: 'afterActivate' | 'beforeDeactivate', labels?: string[] }`** so **`/boot/init.js`** can refresh mount-dependent state without forking HDMS.
|
||||
- Stock booter also calls **`onAfterActivate`** on the **`hdms`** module export when present (see **developer-guide/11-kernel-pear-cookbook.md**).
|
||||
- After **`applyUnlockedEnv`**, the booter’s **`onIdentityUnlocked`** path (**`packages/bare-os-booter/index.js`**) activates **Corestore**, **swarm**, the **personal** drive, and **HDMS** with the mount map. Custom **`/boot/init.js`** may assign **`ctx.onIdentityUnlocked`** for extra post-login hooks (see **`handbook/05-identity-vault-and-hdms.md`**).
|
||||
|
||||
## Execution steps (for the agent)
|
||||
|
||||
1. If the user is **guest**, explain that **mutations** require **`login`** / **`login --new`** first; **`hdms list`** may still work for existing mounts.
|
||||
2. For **subcommands and flags**, prefer **`read_man_page hdms`** when available; otherwise cite **`handbook/05-identity-vault-and-hdms.md`** and **`packages/bare-os-booter/lib/hdms-manager.js`**.
|
||||
3. For **pairing failures**, check timeout env vars, bootstrap connectivity, and whether **`--read-only`** was used inappropriately on invites.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Read-only unless the user explicitly asks to run **`hdms`** mutating commands and policy allows.
|
||||
- Do not promise cross-runtime behavior beyond what **`runHdmsCli`** and Autopass/Hyperdrive versions in this repo implement.
|
||||
- Treat **writer secrets** and **z32 invite tokens** as secrets; do not echo them into logs or chat in full.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: bare-os-holesail
|
||||
version: 1.0.0
|
||||
description: Holesail P2P tunnels in Bare OS — managed state, initd unit bare-holesail, env toggles, and ctx.bare.holesail for /bin scripts.
|
||||
tags: [holesail, p2p, tunnel, initd, bare-modules]
|
||||
requires: [read_man_page, read_file, read_proc_file]
|
||||
---
|
||||
|
||||
# bare-os-holesail Skill
|
||||
|
||||
## When to use
|
||||
|
||||
Use when the user asks about **Holesail** in this repo: exposing TCP/UDP through Holepunch-style tunnels, **`/bin/holesail`** CLI, **`bare-holesail`** initd, **`BARE_OS_HOLESAIL_*`** environment variables, **`ctx.bare.holesail`** from drive bundles, or licensing (**upstream `holesail` is AGPL-3.0**).
|
||||
|
||||
## Mental model
|
||||
|
||||
1. **Integration** lives in **`packages/bare-os-booter/lib/bare-holesail.js`** (initd + optional early “kernel-path” instance) and **`packages/bare-os-booter/lib/holesail-cli.js`** (**`ctx.bareOsRunHolesailCli`** for **`/bin/holesail`**).
|
||||
2. **Resolution order** under **`pear run`**: the booter prefers **`ctx.bare.holesail`** ( **`/lib/bare/bundles/holesail.js`** after drive merge), else host **`import.meta.resolve('holesail')`**, else eval of the drive IIFE bundle via **`ctx.vfs`** — **`/bin`** and **`/boot/init.js`** are **not** Node modules, so scripts must not **`require('holesail')`**.
|
||||
3. **Stock default**: initd unit **`bare-holesail`** is **on** when **`BARE_OS_HOLESAIL_INITD`** and **`BARE_OS_HOLESAIL_MANAGED`** are left at defaults (**`1`** in stock **`shellEnv`** unless the host clears them). Disable with **`BARE_OS_HOLESAIL_INITD=0`** or **`systemctl disable bare-holesail`** (**`~/.config/bare-os/initd/disabled.txt`**).
|
||||
|
||||
## Managed vs single-tunnel mode
|
||||
|
||||
- **Managed (default)** — **`BARE_OS_HOLESAIL_MANAGED=1`**. Persisted tunnel list in **`BARE_OS_HOLESAIL_STATE`** (default **`~/.holesail/state.json`**, on the **personal** drive under the session **`$HOME`**). On unit start, each **enabled** entry gets its own **`holesail`** instance. Operator CLI: **`holesail list`**, **`add`**, **`remove`**, **`start`**, **`stop`**, **`restart`**, **`enable`**, **`disable`**, plus **`path`** (prints resolved state path) and **`help`**.
|
||||
- **Single tunnel** — Set **`BARE_OS_HOLESAIL_MANAGED=0`**, then exactly one of **`BARE_OS_HOLESAIL_SERVER=1`** or **`BARE_OS_HOLESAIL_CLIENT=1`**, and in client mode **`BARE_OS_HOLESAIL_KEY=…`**. Optional: **`BARE_OS_HOLESAIL_SECURE`**, **`PORT`**, **`HOST`**, **`UDP`**, **`LOG`**.
|
||||
|
||||
## Early booter (“kernel-path”) instance
|
||||
|
||||
Separate from initd: enable with **`BARE_OS_HOLESAIL_KERNEL=1`** and the **`BARE_OS_HOLESAIL_KERNEL_*`** mirror env vars (e.g. **`BARE_OS_HOLESAIL_KERNEL_SERVER=1`**). Starts after the **`repl`** boot phase and before **`startBareInitd`**; teardown uses **`registerKernelShutdownHook`**. **`hs.pause()` / `hs.resume()`** tie into mobile suspend/resume with other subsystems.
|
||||
|
||||
## Operator CLI quick reference
|
||||
|
||||
From **`holesail-cli.js`** help text:
|
||||
|
||||
- **`holesail add ID --server|--client`** with optional **`--key`**, bare **`hs://…`** token (no **`--key`** prefix), **`--port`**, **`--host`**, **`--udp`**, **`--secure` / `--no-secure`**, **`--log`**.
|
||||
- **`holesail remove ID`**, **`start|stop|restart ID`**, **`enable|disable ID`**.
|
||||
|
||||
Initd starts after **`kernel-logger`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
|
||||
## Debugging and safety
|
||||
|
||||
- **`BARE_OS_HOLESAIL_DEBUG=1`** — extra console lines (**URLs only**; keys are not logged in full).
|
||||
- Do **not** paste full connection secrets into chat or commit logs; redact **`hs://`** payloads when summarizing.
|
||||
- **`read_man_page holesail`** (after a coreutils/man build) for in-image synopsis; **`handbook/04-the-booter-runtime.md`** § **bare-holesail** is the prose source of truth for this repo.
|
||||
|
||||
## Execution steps (for the agent)
|
||||
|
||||
1. Confirm whether the question is **operator tunnels** (CLI + state file + initd) vs **guest scripting** (**`ctx.bare.holesail`**).
|
||||
2. If live behavior matters, prefer **`read_proc_file`** / initd journal paths the user can access over guessing from docs.
|
||||
3. Mention **AGPL** when the user plans to redistribute or ship a product that bundles **`holesail`**.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Read-only unless the user explicitly authorizes changing env, initd disables, or **`holesail add`** state.
|
||||
- Do not assume **`holesail`** is **`import()`**-able from **`pear:`** without **`ctx.bare`** or the drive bundle.
|
||||
File diff suppressed because one or more lines are too long
@@ -25,7 +25,9 @@ var BARE_AGENT_SKILL_SEED_REL = Object.freeze([
|
||||
'skills/.gitkeep',
|
||||
'skills/p2p-os-status/SKILL.md',
|
||||
'skills/bare-os-kernel-proc/SKILL.md',
|
||||
'skills/bare-os-super-developer/SKILL.md'
|
||||
'skills/bare-os-super-developer/SKILL.md',
|
||||
'skills/holesail/SKILL.md',
|
||||
'skills/hdms/SKILL.md'
|
||||
])
|
||||
|
||||
/**
|
||||
|
||||
@@ -22,7 +22,7 @@ This tree follows the **agent** Markdown workspace convention: “soul” files
|
||||
3. During a session, the model loads the full document with the **`read_skill`** tool (do not paste huge skills into the user channel unless asked).
|
||||
4. Shared skills can live under **`~/.agent/skills/`**; keep **`workspace/skills/`** for machine-local or repo-specific behavior.
|
||||
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, and **`bare-os-super-developer`** (writing guest scripts/apps and navigating **`ctx`**).
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (Holesail tunnels / initd), and **`hdms`** (Hyperdrive mounts and invite/pair).
|
||||
|
||||
After **`agent --config`** / **`--setup`** (or changing **`owner_name`** / **`agent_label`** via **`edit_agent_config`**), **`IDENTITY.md`** and **`USER.md`** are regenerated from **`config.json`** so the workspace matches the operator and agent label.
|
||||
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: bare-os-hdms
|
||||
version: 1.0.0
|
||||
description: HDMS — extra Hyperdrives under /mnt, registry on the personal drive, Autopass invite/pair, and identity-gated ctx.runHdms.
|
||||
tags: [hdms, hyperdrive, identity, autopass, mounts]
|
||||
requires: [read_man_page, read_file, vfs]
|
||||
---
|
||||
|
||||
# bare-os-hdms Skill
|
||||
|
||||
## When to use
|
||||
|
||||
Use when the user asks about **HDMS** (Hyperdrive Management): **`hdms`** CLI, **`/.bare/hdms/registry.json`**, **`/mnt/<label>`** mounts, **invite/pair** sharing, **`ctx.runHdms`**, **`ctx.bareOsSubscribeHdmsLifecycle`**, or how HDMS relates to **`login`** / guest mode.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **HDMS activates after identity unlock.** Guest sessions can **list** mounts that are already open; **mutating** commands (**`create`**, **`add`**, registry edits, **`invite`**, **`pair`**, etc.) go through **`assertLoggedIn`**: require **`ctx.identity.state === 'unlocked'`** and an active HDMS controller.
|
||||
- Implementation: **`packages/bare-os-booter/lib/hdms-manager.js`** (**`runHdmsCli`**, **`HdmsController`**), exposed as **`ctx.runHdms(argv)`** in **`packages/bare-os-booter/index.js`**.
|
||||
|
||||
## Registry and VFS
|
||||
|
||||
- **Registry path (constant):** **`/.bare/hdms/registry.json`** on the **personal** drive (**`HDMS_REGISTRY_PATH`**).
|
||||
- **Writable mounts:** **`hdms create <label>`** — new Corestore namespace + Hyperdrive, replicate to swarm.
|
||||
- **Read-only by key:** **`hdms add <label> <z32-key>`** — open an existing drive by key string.
|
||||
- **VFS:** paths **`/mnt/<label>/…`**; writable mounts allow **`put`** on those routes.
|
||||
|
||||
## Invite and pair (Autopass / BlindPairing)
|
||||
|
||||
High-level behavior (details and caveats in **`handbook/05-identity-vault-and-hdms.md`**):
|
||||
|
||||
- **Invite with a drive:** **`hdms invite [--read-only] <label>`** stores a pending share for the peer. **`--rw`** uses a separate Autopass key (**`pending-share-rw`**) with **`signerKey`** + **`writerSecretHex`** so peers do not silently mount read-only when read/write was intended. **Anyone who can read the paired Autopass ledger can write the drive** — treat **`--rw`** as highly sensitive.
|
||||
- **`hdms invite --read-only`** on a writable label sets the peer’s Autopass writer row read-only; **read-only Autobase writers are not append-capable**, so **`invite --read-only` + `pair` often fails** with “Not writable” / timeout — for normal HDMS pairing, omit **`--read-only`** unless you understand the limitation.
|
||||
- **Pair:** **`hdms pair [--persist|--no-persist] <invite>`** — bounded waits (**`BARE_OS_HDMS_PAIR_WAIT_MS`**, **`BARE_OS_HDMS_PAIR_READY_MS`**, **`BARE_OS_HDMS_PAIR_SHARE_WAIT_MS`**, **`BARE_OS_HDMS_INVITE_CLEAR_MS`** — see env appendix / booter). Default persists to registry; **`--no-persist`** keeps the mount **ephemeral**. Inviter must stay **online** with matching **Hyperswarm bootstrap** or pairing stalls.
|
||||
- **Invite without a label:** **`hdms invite`** (optional **`--read-only`**) only pairs Autopass; pending drive offers are cleared — **no automatic `/mnt` mount** for the peer.
|
||||
|
||||
## Kernel hooks
|
||||
|
||||
- **`ctx.bareOsSubscribeHdmsLifecycle(fn)`** — callback with **`{ kind: 'afterActivate' | 'beforeDeactivate', labels?: string[] }`** so **`/boot/init.js`** can refresh mount-dependent state without forking HDMS.
|
||||
- Stock booter also calls **`onAfterActivate`** on the **`hdms`** module export when present (see **developer-guide/11-kernel-pear-cookbook.md**).
|
||||
- After **`applyUnlockedEnv`**, the booter’s **`onIdentityUnlocked`** path (**`packages/bare-os-booter/index.js`**) activates **Corestore**, **swarm**, the **personal** drive, and **HDMS** with the mount map. Custom **`/boot/init.js`** may assign **`ctx.onIdentityUnlocked`** for extra post-login hooks (see **`handbook/05-identity-vault-and-hdms.md`**).
|
||||
|
||||
## Execution steps (for the agent)
|
||||
|
||||
1. If the user is **guest**, explain that **mutations** require **`login`** / **`login --new`** first; **`hdms list`** may still work for existing mounts.
|
||||
2. For **subcommands and flags**, prefer **`read_man_page hdms`** when available; otherwise cite **`handbook/05-identity-vault-and-hdms.md`** and **`packages/bare-os-booter/lib/hdms-manager.js`**.
|
||||
3. For **pairing failures**, check timeout env vars, bootstrap connectivity, and whether **`--read-only`** was used inappropriately on invites.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Read-only unless the user explicitly asks to run **`hdms`** mutating commands and policy allows.
|
||||
- Do not promise cross-runtime behavior beyond what **`runHdmsCli`** and Autopass/Hyperdrive versions in this repo implement.
|
||||
- Treat **writer secrets** and **z32 invite tokens** as secrets; do not echo them into logs or chat in full.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: bare-os-holesail
|
||||
version: 1.0.0
|
||||
description: Holesail P2P tunnels in Bare OS — managed state, initd unit bare-holesail, env toggles, and ctx.bare.holesail for /bin scripts.
|
||||
tags: [holesail, p2p, tunnel, initd, bare-modules]
|
||||
requires: [read_man_page, read_file, read_proc_file]
|
||||
---
|
||||
|
||||
# bare-os-holesail Skill
|
||||
|
||||
## When to use
|
||||
|
||||
Use when the user asks about **Holesail** in this repo: exposing TCP/UDP through Holepunch-style tunnels, **`/bin/holesail`** CLI, **`bare-holesail`** initd, **`BARE_OS_HOLESAIL_*`** environment variables, **`ctx.bare.holesail`** from drive bundles, or licensing (**upstream `holesail` is AGPL-3.0**).
|
||||
|
||||
## Mental model
|
||||
|
||||
1. **Integration** lives in **`packages/bare-os-booter/lib/bare-holesail.js`** (initd + optional early “kernel-path” instance) and **`packages/bare-os-booter/lib/holesail-cli.js`** (**`ctx.bareOsRunHolesailCli`** for **`/bin/holesail`**).
|
||||
2. **Resolution order** under **`pear run`**: the booter prefers **`ctx.bare.holesail`** ( **`/lib/bare/bundles/holesail.js`** after drive merge), else host **`import.meta.resolve('holesail')`**, else eval of the drive IIFE bundle via **`ctx.vfs`** — **`/bin`** and **`/boot/init.js`** are **not** Node modules, so scripts must not **`require('holesail')`**.
|
||||
3. **Stock default**: initd unit **`bare-holesail`** is **on** when **`BARE_OS_HOLESAIL_INITD`** and **`BARE_OS_HOLESAIL_MANAGED`** are left at defaults (**`1`** in stock **`shellEnv`** unless the host clears them). Disable with **`BARE_OS_HOLESAIL_INITD=0`** or **`systemctl disable bare-holesail`** (**`~/.config/bare-os/initd/disabled.txt`**).
|
||||
|
||||
## Managed vs single-tunnel mode
|
||||
|
||||
- **Managed (default)** — **`BARE_OS_HOLESAIL_MANAGED=1`**. Persisted tunnel list in **`BARE_OS_HOLESAIL_STATE`** (default **`~/.holesail/state.json`**, on the **personal** drive under the session **`$HOME`**). On unit start, each **enabled** entry gets its own **`holesail`** instance. Operator CLI: **`holesail list`**, **`add`**, **`remove`**, **`start`**, **`stop`**, **`restart`**, **`enable`**, **`disable`**, plus **`path`** (prints resolved state path) and **`help`**.
|
||||
- **Single tunnel** — Set **`BARE_OS_HOLESAIL_MANAGED=0`**, then exactly one of **`BARE_OS_HOLESAIL_SERVER=1`** or **`BARE_OS_HOLESAIL_CLIENT=1`**, and in client mode **`BARE_OS_HOLESAIL_KEY=…`**. Optional: **`BARE_OS_HOLESAIL_SECURE`**, **`PORT`**, **`HOST`**, **`UDP`**, **`LOG`**.
|
||||
|
||||
## Early booter (“kernel-path”) instance
|
||||
|
||||
Separate from initd: enable with **`BARE_OS_HOLESAIL_KERNEL=1`** and the **`BARE_OS_HOLESAIL_KERNEL_*`** mirror env vars (e.g. **`BARE_OS_HOLESAIL_KERNEL_SERVER=1`**). Starts after the **`repl`** boot phase and before **`startBareInitd`**; teardown uses **`registerKernelShutdownHook`**. **`hs.pause()` / `hs.resume()`** tie into mobile suspend/resume with other subsystems.
|
||||
|
||||
## Operator CLI quick reference
|
||||
|
||||
From **`holesail-cli.js`** help text:
|
||||
|
||||
- **`holesail add ID --server|--client`** with optional **`--key`**, bare **`hs://…`** token (no **`--key`** prefix), **`--port`**, **`--host`**, **`--udp`**, **`--secure` / `--no-secure`**, **`--log`**.
|
||||
- **`holesail remove ID`**, **`start|stop|restart ID`**, **`enable|disable ID`**.
|
||||
|
||||
Initd starts after **`kernel-logger`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
|
||||
## Debugging and safety
|
||||
|
||||
- **`BARE_OS_HOLESAIL_DEBUG=1`** — extra console lines (**URLs only**; keys are not logged in full).
|
||||
- Do **not** paste full connection secrets into chat or commit logs; redact **`hs://`** payloads when summarizing.
|
||||
- **`read_man_page holesail`** (after a coreutils/man build) for in-image synopsis; **`handbook/04-the-booter-runtime.md`** § **bare-holesail** is the prose source of truth for this repo.
|
||||
|
||||
## Execution steps (for the agent)
|
||||
|
||||
1. Confirm whether the question is **operator tunnels** (CLI + state file + initd) vs **guest scripting** (**`ctx.bare.holesail`**).
|
||||
2. If live behavior matters, prefer **`read_proc_file`** / initd journal paths the user can access over guessing from docs.
|
||||
3. Mention **AGPL** when the user plans to redistribute or ship a product that bundles **`holesail`**.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Read-only unless the user explicitly authorizes changing env, initd disables, or **`holesail add`** state.
|
||||
- Do not assume **`holesail`** is **`import()`**-able from **`pear:`** without **`ctx.bare`** or the drive bundle.
|
||||
@@ -117,6 +117,8 @@ test('bareAgentEnsureSkillTemplates copies skill seeds when missing', async (t)
|
||||
set('/share/agent-workspace/skills/p2p-os-status/SKILL.md', '# Skill')
|
||||
set('/share/agent-workspace/skills/bare-os-kernel-proc/SKILL.md', '# Proc skill')
|
||||
set('/share/agent-workspace/skills/bare-os-super-developer/SKILL.md', '# Dev skill')
|
||||
set('/share/agent-workspace/skills/holesail/SKILL.md', '# Holesail skill')
|
||||
set('/share/agent-workspace/skills/hdms/SKILL.md', '# Hdms skill')
|
||||
set('/share/agent-workspace/skill-loader.stub.js', '// stub')
|
||||
const vfs = {
|
||||
async mkdir(_p, _o) {},
|
||||
@@ -146,6 +148,8 @@ test('bareAgentEnsureSkillTemplates copies skill seeds when missing', async (t)
|
||||
t.ok(written.some(([p]) => p === '/home/x/.agent/workspace/skills/p2p-os-status/SKILL.md'))
|
||||
t.ok(written.some(([p]) => p === '/home/x/.agent/workspace/skills/bare-os-kernel-proc/SKILL.md'))
|
||||
t.ok(written.some(([p]) => p === '/home/x/.agent/workspace/skills/bare-os-super-developer/SKILL.md'))
|
||||
t.ok(written.some(([p]) => p === '/home/x/.agent/workspace/skills/holesail/SKILL.md'))
|
||||
t.ok(written.some(([p]) => p === '/home/x/.agent/workspace/skills/hdms/SKILL.md'))
|
||||
t.ok(written.some(([p]) => p === '/home/x/.agent/skill-loader.js'))
|
||||
})
|
||||
|
||||
|
||||
@@ -1491,7 +1491,9 @@ var BARE_AGENT_SKILL_SEED_REL = Object.freeze([
|
||||
'skills/.gitkeep',
|
||||
'skills/p2p-os-status/SKILL.md',
|
||||
'skills/bare-os-kernel-proc/SKILL.md',
|
||||
'skills/bare-os-super-developer/SKILL.md'
|
||||
'skills/bare-os-super-developer/SKILL.md',
|
||||
'skills/holesail/SKILL.md',
|
||||
'skills/hdms/SKILL.md'
|
||||
])
|
||||
|
||||
/**
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"schema": 2,
|
||||
"profileId": "bare-os-posix-like",
|
||||
"generatedAt": "2026-04-22T07:14:40.458Z",
|
||||
"generatedAt": "2026-04-22T07:30:25.994Z",
|
||||
"note": "Sparse POSIX Issue 7 coverage hints for /bin utilities. Omitted command names are not yet profiled here.",
|
||||
"commandIndex": [
|
||||
{
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"schema": 1,
|
||||
"atMs": 1776842080458,
|
||||
"atMs": 1776843025994,
|
||||
"commands": [
|
||||
"agent",
|
||||
"arch",
|
||||
|
||||
@@ -22,7 +22,7 @@ This tree follows the **agent** Markdown workspace convention: “soul” files
|
||||
3. During a session, the model loads the full document with the **`read_skill`** tool (do not paste huge skills into the user channel unless asked).
|
||||
4. Shared skills can live under **`~/.agent/skills/`**; keep **`workspace/skills/`** for machine-local or repo-specific behavior.
|
||||
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, and **`bare-os-super-developer`** (writing guest scripts/apps and navigating **`ctx`**).
|
||||
Seeded examples in this repo (under **`skills/`**): **`p2p-os-status`**, **`bare-os-kernel-proc`**, **`bare-os-super-developer`**, **`holesail`** (Holesail tunnels / initd), and **`hdms`** (Hyperdrive mounts and invite/pair).
|
||||
|
||||
After **`agent --config`** / **`--setup`** (or changing **`owner_name`** / **`agent_label`** via **`edit_agent_config`**), **`IDENTITY.md`** and **`USER.md`** are regenerated from **`config.json`** so the workspace matches the operator and agent label.
|
||||
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: bare-os-hdms
|
||||
version: 1.0.0
|
||||
description: HDMS — extra Hyperdrives under /mnt, registry on the personal drive, Autopass invite/pair, and identity-gated ctx.runHdms.
|
||||
tags: [hdms, hyperdrive, identity, autopass, mounts]
|
||||
requires: [read_man_page, read_file, vfs]
|
||||
---
|
||||
|
||||
# bare-os-hdms Skill
|
||||
|
||||
## When to use
|
||||
|
||||
Use when the user asks about **HDMS** (Hyperdrive Management): **`hdms`** CLI, **`/.bare/hdms/registry.json`**, **`/mnt/<label>`** mounts, **invite/pair** sharing, **`ctx.runHdms`**, **`ctx.bareOsSubscribeHdmsLifecycle`**, or how HDMS relates to **`login`** / guest mode.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **HDMS activates after identity unlock.** Guest sessions can **list** mounts that are already open; **mutating** commands (**`create`**, **`add`**, registry edits, **`invite`**, **`pair`**, etc.) go through **`assertLoggedIn`**: require **`ctx.identity.state === 'unlocked'`** and an active HDMS controller.
|
||||
- Implementation: **`packages/bare-os-booter/lib/hdms-manager.js`** (**`runHdmsCli`**, **`HdmsController`**), exposed as **`ctx.runHdms(argv)`** in **`packages/bare-os-booter/index.js`**.
|
||||
|
||||
## Registry and VFS
|
||||
|
||||
- **Registry path (constant):** **`/.bare/hdms/registry.json`** on the **personal** drive (**`HDMS_REGISTRY_PATH`**).
|
||||
- **Writable mounts:** **`hdms create <label>`** — new Corestore namespace + Hyperdrive, replicate to swarm.
|
||||
- **Read-only by key:** **`hdms add <label> <z32-key>`** — open an existing drive by key string.
|
||||
- **VFS:** paths **`/mnt/<label>/…`**; writable mounts allow **`put`** on those routes.
|
||||
|
||||
## Invite and pair (Autopass / BlindPairing)
|
||||
|
||||
High-level behavior (details and caveats in **`handbook/05-identity-vault-and-hdms.md`**):
|
||||
|
||||
- **Invite with a drive:** **`hdms invite [--read-only] <label>`** stores a pending share for the peer. **`--rw`** uses a separate Autopass key (**`pending-share-rw`**) with **`signerKey`** + **`writerSecretHex`** so peers do not silently mount read-only when read/write was intended. **Anyone who can read the paired Autopass ledger can write the drive** — treat **`--rw`** as highly sensitive.
|
||||
- **`hdms invite --read-only`** on a writable label sets the peer’s Autopass writer row read-only; **read-only Autobase writers are not append-capable**, so **`invite --read-only` + `pair` often fails** with “Not writable” / timeout — for normal HDMS pairing, omit **`--read-only`** unless you understand the limitation.
|
||||
- **Pair:** **`hdms pair [--persist|--no-persist] <invite>`** — bounded waits (**`BARE_OS_HDMS_PAIR_WAIT_MS`**, **`BARE_OS_HDMS_PAIR_READY_MS`**, **`BARE_OS_HDMS_PAIR_SHARE_WAIT_MS`**, **`BARE_OS_HDMS_INVITE_CLEAR_MS`** — see env appendix / booter). Default persists to registry; **`--no-persist`** keeps the mount **ephemeral**. Inviter must stay **online** with matching **Hyperswarm bootstrap** or pairing stalls.
|
||||
- **Invite without a label:** **`hdms invite`** (optional **`--read-only`**) only pairs Autopass; pending drive offers are cleared — **no automatic `/mnt` mount** for the peer.
|
||||
|
||||
## Kernel hooks
|
||||
|
||||
- **`ctx.bareOsSubscribeHdmsLifecycle(fn)`** — callback with **`{ kind: 'afterActivate' | 'beforeDeactivate', labels?: string[] }`** so **`/boot/init.js`** can refresh mount-dependent state without forking HDMS.
|
||||
- Stock booter also calls **`onAfterActivate`** on the **`hdms`** module export when present (see **developer-guide/11-kernel-pear-cookbook.md**).
|
||||
- After **`applyUnlockedEnv`**, the booter’s **`onIdentityUnlocked`** path (**`packages/bare-os-booter/index.js`**) activates **Corestore**, **swarm**, the **personal** drive, and **HDMS** with the mount map. Custom **`/boot/init.js`** may assign **`ctx.onIdentityUnlocked`** for extra post-login hooks (see **`handbook/05-identity-vault-and-hdms.md`**).
|
||||
|
||||
## Execution steps (for the agent)
|
||||
|
||||
1. If the user is **guest**, explain that **mutations** require **`login`** / **`login --new`** first; **`hdms list`** may still work for existing mounts.
|
||||
2. For **subcommands and flags**, prefer **`read_man_page hdms`** when available; otherwise cite **`handbook/05-identity-vault-and-hdms.md`** and **`packages/bare-os-booter/lib/hdms-manager.js`**.
|
||||
3. For **pairing failures**, check timeout env vars, bootstrap connectivity, and whether **`--read-only`** was used inappropriately on invites.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Read-only unless the user explicitly asks to run **`hdms`** mutating commands and policy allows.
|
||||
- Do not promise cross-runtime behavior beyond what **`runHdmsCli`** and Autopass/Hyperdrive versions in this repo implement.
|
||||
- Treat **writer secrets** and **z32 invite tokens** as secrets; do not echo them into logs or chat in full.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: bare-os-holesail
|
||||
version: 1.0.0
|
||||
description: Holesail P2P tunnels in Bare OS — managed state, initd unit bare-holesail, env toggles, and ctx.bare.holesail for /bin scripts.
|
||||
tags: [holesail, p2p, tunnel, initd, bare-modules]
|
||||
requires: [read_man_page, read_file, read_proc_file]
|
||||
---
|
||||
|
||||
# bare-os-holesail Skill
|
||||
|
||||
## When to use
|
||||
|
||||
Use when the user asks about **Holesail** in this repo: exposing TCP/UDP through Holepunch-style tunnels, **`/bin/holesail`** CLI, **`bare-holesail`** initd, **`BARE_OS_HOLESAIL_*`** environment variables, **`ctx.bare.holesail`** from drive bundles, or licensing (**upstream `holesail` is AGPL-3.0**).
|
||||
|
||||
## Mental model
|
||||
|
||||
1. **Integration** lives in **`packages/bare-os-booter/lib/bare-holesail.js`** (initd + optional early “kernel-path” instance) and **`packages/bare-os-booter/lib/holesail-cli.js`** (**`ctx.bareOsRunHolesailCli`** for **`/bin/holesail`**).
|
||||
2. **Resolution order** under **`pear run`**: the booter prefers **`ctx.bare.holesail`** ( **`/lib/bare/bundles/holesail.js`** after drive merge), else host **`import.meta.resolve('holesail')`**, else eval of the drive IIFE bundle via **`ctx.vfs`** — **`/bin`** and **`/boot/init.js`** are **not** Node modules, so scripts must not **`require('holesail')`**.
|
||||
3. **Stock default**: initd unit **`bare-holesail`** is **on** when **`BARE_OS_HOLESAIL_INITD`** and **`BARE_OS_HOLESAIL_MANAGED`** are left at defaults (**`1`** in stock **`shellEnv`** unless the host clears them). Disable with **`BARE_OS_HOLESAIL_INITD=0`** or **`systemctl disable bare-holesail`** (**`~/.config/bare-os/initd/disabled.txt`**).
|
||||
|
||||
## Managed vs single-tunnel mode
|
||||
|
||||
- **Managed (default)** — **`BARE_OS_HOLESAIL_MANAGED=1`**. Persisted tunnel list in **`BARE_OS_HOLESAIL_STATE`** (default **`~/.holesail/state.json`**, on the **personal** drive under the session **`$HOME`**). On unit start, each **enabled** entry gets its own **`holesail`** instance. Operator CLI: **`holesail list`**, **`add`**, **`remove`**, **`start`**, **`stop`**, **`restart`**, **`enable`**, **`disable`**, plus **`path`** (prints resolved state path) and **`help`**.
|
||||
- **Single tunnel** — Set **`BARE_OS_HOLESAIL_MANAGED=0`**, then exactly one of **`BARE_OS_HOLESAIL_SERVER=1`** or **`BARE_OS_HOLESAIL_CLIENT=1`**, and in client mode **`BARE_OS_HOLESAIL_KEY=…`**. Optional: **`BARE_OS_HOLESAIL_SECURE`**, **`PORT`**, **`HOST`**, **`UDP`**, **`LOG`**.
|
||||
|
||||
## Early booter (“kernel-path”) instance
|
||||
|
||||
Separate from initd: enable with **`BARE_OS_HOLESAIL_KERNEL=1`** and the **`BARE_OS_HOLESAIL_KERNEL_*`** mirror env vars (e.g. **`BARE_OS_HOLESAIL_KERNEL_SERVER=1`**). Starts after the **`repl`** boot phase and before **`startBareInitd`**; teardown uses **`registerKernelShutdownHook`**. **`hs.pause()` / `hs.resume()`** tie into mobile suspend/resume with other subsystems.
|
||||
|
||||
## Operator CLI quick reference
|
||||
|
||||
From **`holesail-cli.js`** help text:
|
||||
|
||||
- **`holesail add ID --server|--client`** with optional **`--key`**, bare **`hs://…`** token (no **`--key`** prefix), **`--port`**, **`--host`**, **`--udp`**, **`--secure` / `--no-secure`**, **`--log`**.
|
||||
- **`holesail remove ID`**, **`start|stop|restart ID`**, **`enable|disable ID`**.
|
||||
|
||||
Initd starts after **`kernel-logger`** by default. Logs: **`/var/log/bare-os/holesail.log`**. Example unit drop-in: **`/etc/bare-os/units/bare-holesail.unit.example`** on the system image.
|
||||
|
||||
## Debugging and safety
|
||||
|
||||
- **`BARE_OS_HOLESAIL_DEBUG=1`** — extra console lines (**URLs only**; keys are not logged in full).
|
||||
- Do **not** paste full connection secrets into chat or commit logs; redact **`hs://`** payloads when summarizing.
|
||||
- **`read_man_page holesail`** (after a coreutils/man build) for in-image synopsis; **`handbook/04-the-booter-runtime.md`** § **bare-holesail** is the prose source of truth for this repo.
|
||||
|
||||
## Execution steps (for the agent)
|
||||
|
||||
1. Confirm whether the question is **operator tunnels** (CLI + state file + initd) vs **guest scripting** (**`ctx.bare.holesail`**).
|
||||
2. If live behavior matters, prefer **`read_proc_file`** / initd journal paths the user can access over guessing from docs.
|
||||
3. Mention **AGPL** when the user plans to redistribute or ship a product that bundles **`holesail`**.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Read-only unless the user explicitly authorizes changing env, initd disables, or **`holesail add`** state.
|
||||
- Do not assume **`holesail`** is **`import()`**-able from **`pear:`** without **`ctx.bare`** or the drive bundle.
|
||||
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user