85 lines
5.5 KiB
Markdown
85 lines
5.5 KiB
Markdown
# Bare OS agent — Markdown workspace
|
|
|
|
This tree follows the **agent** Markdown workspace convention: “soul” files under **`workspace/`** define personality, rules, and memory. **`/bin/agent`** loads them into the LLM **system prompt** on each session (after seeding from **`/share/agent-workspace/`** on the system drive if `~/.agent/workspace/SOUL.md` is missing).
|
|
|
|
## Layout (personal Hyperdrive)
|
|
|
|
| Path | Role |
|
|
| --- | --- |
|
|
| **`~/.agent/workspace/`** | Agent brain — **git-trackable**, portable across peers |
|
|
| **`~/.agent/workspace/skills/`** | Modular **skills** — one folder per skill, each with **`SKILL.md`** (optional YAML frontmatter) |
|
|
| **`~/.agent/workspace/memory/`** | Daily append logs `YYYY-MM-DD.md` (optional) |
|
|
| **`~/.agent/skills/`** | Optional **global** skills (lower precedence than `workspace/skills/` when names collide) |
|
|
| **`~/.agent/config.json`** | Backend (`qvac` / `rest`), model, API URL/key (REST), and reasoning/process visibility controls |
|
|
| **`~/.agent/skill-loader.js`** | Host stub for `discoverSkills` / `loadSkill` (in-image agent uses bundled discovery + **`read_skill`** tool) |
|
|
| **`~/.agent/loader.js`** | Stub / hook for **host-side** experimentation (not used by `/bin/agent` bundle) |
|
|
| **`~/.agent/index.js`** | Stub factory reference (in-image agent uses built-in loader) |
|
|
|
|
## Skills
|
|
|
|
1. Add a directory under **`~/.agent/workspace/skills/<skill-id>/`** with a **`SKILL.md`** file.
|
|
2. Use YAML frontmatter for **`name`**, **`description`**, **`version`**, etc. The compact system prompt lists **id**, **name**, and a short **description** only.
|
|
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`**, **`bare-os-super-developer`**, **`agent-ops`**, **`holesail`** (managed **`state.json`**, **`seed`**/**`key`**, stock **`bare-www-*`** / **`bare-ssh-*`**), and **`hdms`** (Hyperdrive mounts and invite/pair). Provider-specific skill **`xai-compat`** is only seeded when `provider` is configured as `xai`.
|
|
|
|
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.
|
|
|
|
## Inference backends
|
|
|
|
Default backend is **QVAC** (QuantumVerse Automatic Computer) — local in-process LLM via the booter **`ctx.bareOsQvac*`** bridge (`@qvac/sdk`). Weights download on first use after you pick a profile in **`agent --config`**.
|
|
|
|
- `backend` — `qvac` (default) or `rest`
|
|
- `qvac_profile` — `lite` / `recommended` / `strong` / `tool-tiny`
|
|
- `qvac_model` — registry id (e.g. `QWEN3_1_7B_INST_Q4`)
|
|
- `qvac_ctx_size` — optional context window override (profile defaults: lite/tool-tiny 4096, recommended/strong 8192; max 32768)
|
|
- `qvac_device` — `gpu` (default) or `cpu` (bypass Vulkan; slower)
|
|
- `qvac_main_gpu` — `auto` (default: pick highest-VRAM Vulkan GPU, else CPU), `dedicated`, `integrated`, or device index (`0`, `1`, …)
|
|
- `qvac_gpu_layers` — optional layer offload count (`0` = CPU weights)
|
|
|
|
Set **`BARE_OS_SKIP_QVAC=1`** on the host (or pack with **`--skip-qvac`**) to stub QVAC natives; then choose **REST** in config.
|
|
|
|
REST (OpenAI-compatible) remains fully supported:
|
|
|
|
- `rest_base_url`, `rest_api_key`, `model`, `provider` (`groq` / `xai` / …)
|
|
- `groq` profile defaults to `https://api.groq.com/openai/v1`
|
|
- `xai` profile defaults to `https://api.x.ai/v1`
|
|
|
|
Reasoning/process visibility is configurable in `config.json`:
|
|
|
|
- `show_reasoning` — master toggle
|
|
- `reasoning_mode` — `off` / `summary` / `trace`
|
|
- `reasoning_max_chars` — bounded reasoning output
|
|
- `reasoning_include_tools` — include tool traces in process stream
|
|
|
|
Max-autonomy bridge policy switches are also in `config.json`:
|
|
|
|
- `allow_bridge_mutations` — master mutation gate
|
|
- `allow_host_notifications` — notification route gate
|
|
- `allow_host_actions` — host action route gate
|
|
- `emergency_stop_mutations` — kill switch for mutating bridge tools
|
|
|
|
Autonomous coding runner controls in `config.json`:
|
|
|
|
- `autonomous_mode_enabled` — master toggle for autonomous loop mode
|
|
- `autonomous_max_runtime_ms` — runtime timebox for autonomous sessions
|
|
- `autonomous_completion_required_checks` — quality gates that must pass before done
|
|
- `autonomous_allow_paths` — allowed write/shell scope paths (`*` for unrestricted by path policy)
|
|
- `autonomous_deny_ops` — hard denylist of tool operations blocked during autonomous runs
|
|
- `autonomous_active`, `autonomous_stop_requested`, `autonomous_status`, `autonomous_last_error` — run state/status fields managed by tools/runtime
|
|
|
|
## Editing
|
|
|
|
1. Change files under **`~/.agent/workspace/`** on your **personal** drive.
|
|
2. Restart **`agent`** or start a new session so the system message reloads.
|
|
3. Keep **`SOUL.md`** / **`AGENTS.md`** stable within a session if you follow the drift guard in **`AGENTS.md`**.
|
|
|
|
## Defaults in this repository
|
|
|
|
Source templates: **`packages/bare-os-coreutils/share/agent-workspace/`** — copied to **`kernel/share/agent-workspace/`** during **`npm run build -w bare-os-coreutils`** for seeding into new homes.
|
|
|
|
## Compatibility
|
|
|
|
File names and load order match common **agent** Markdown layouts so templates can be dropped into **`workspace/`** with minimal edits.
|