Developer Skill
This commit is contained in:
Raven Scott
@@ -98,7 +98,7 @@ The in-image **`/bin/agent`** loads a Markdown workspace from **`~/.agent/worksp
|
||||
|
||||
- **Templates in git:** [`packages/bare-os-coreutils/share/agent-workspace/`](packages/bare-os-coreutils/share/agent-workspace/) — copied to **`kernel/share/agent-workspace/`** by **`npm run build -w bare-os-coreutils`**.
|
||||
- **Host sample prompt:** **`npm run sample:agent-workspace`** — prints a concatenated preview from the repo share (no booter required).
|
||||
- **Skills:** modular **`SKILL.md`** trees under **`~/.agent/workspace/skills/`** (optional **`~/.agent/skills/`**); **`/bin/agent`** appends a compact index to the system message and exposes the **`read_skill`** tool for full instructions.
|
||||
- **Skills:** modular **`SKILL.md`** trees under **`~/.agent/workspace/skills/`** (optional **`~/.agent/skills/`**); **`/bin/agent`** appends a compact index to the system message and exposes the **`read_skill`** tool for full instructions. Seeded examples include **`bare-os-super-developer`** (**`ctx`**, scripts, small apps).
|
||||
- **First-time config:** **`agent --setup`** or **`agent --config`** runs a plain TTY wizard (owner name, agent label, API URL/key/model/provider) and seeds **`~/.agent/workspace/`** from **`/share/agent-workspace/`** when **`SOUL.md`** is missing; **`--config`** is an alias for **`--setup`**.
|
||||
- **Runtime docs:** seeded **`~/.agent/README-agent.md`** after first seed; see also **`man agent`** and [User manual — ch.4](users-manual/04-shell-path-and-scripts.md).
|
||||
|
||||
|
||||
+2
-1
@@ -1490,7 +1490,8 @@ var BARE_AGENT_WORKSPACE_SHARE = '/share/agent-workspace'
|
||||
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-kernel-proc/SKILL.md',
|
||||
'skills/bare-os-super-developer/SKILL.md'
|
||||
])
|
||||
|
||||
/**
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"schema": 2,
|
||||
"profileId": "bare-os-posix-like",
|
||||
"generatedAt": "2026-04-22T07:06:59.998Z",
|
||||
"generatedAt": "2026-04-22T07:14:40.458Z",
|
||||
"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": 1776841619998,
|
||||
"atMs": 1776842080458,
|
||||
"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`** (P2P / drive health style checks) and **`bare-os-kernel-proc`** (authoritative **`/proc/bare_os/*`** reads vs man-page guessing).
|
||||
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`**).
|
||||
|
||||
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,124 @@
|
||||
---
|
||||
name: bare-os-super-developer
|
||||
version: 1.0.0
|
||||
description: Write Bare OS scripts and small apps using ctx — VFS, execLine, hooks, caps, and safe patterns (no Node in /bin/agent loop).
|
||||
tags: [bare-os, ctx, scripts, vfs, kernel, developer]
|
||||
requires: [read_file, read_proc_file, run_js_script]
|
||||
---
|
||||
|
||||
# bare-os-super-developer — Scripts, apps, and `ctx`
|
||||
|
||||
## When to use
|
||||
|
||||
Use this skill when you (or the user) need to **author or debug** Bare OS **JavaScript** that runs **inside the guest** (kernel init, `/bin/*` utilities, `kernel.ext.d`, user `.mjs` run via **`run_js_script`**, or Pear/booter-hosted scripts). It complements repo docs: treat **`developer-guide/02-the-context-object.md`** and **`packages/bare-os-booter/lib/bare-os-ctx.d.ts`** as the canonical deep dives; this file is the **fast mental model**.
|
||||
|
||||
## Core model
|
||||
|
||||
1. **Entrypoints** — Kernel: **`async function start(ctx)`** in `/boot/init.js` (or your image). Commands: **`async function run(ctx, argv)`** where **`argv[0]`** is the invoked name (e.g. `agent`). You **must** set **`ctx.exitCode`** (number) before returning on failure paths.
|
||||
2. **`ctx` is not Node** — There is no full **`process`**, no **`require('node:fs')`**. The booter assembles **`ctx`** as the narrow **syscall surface**: **`vfs`**, **`env`**, **`execLine`**, **`runBinCommand`**, optional **`httpFetch`**, **`bare`**, identity helpers, diagnostics, etc. See the mermaid overview in Chapter 2 of the developer guide.
|
||||
3. **`/bin/agent` is special** — The agent bundle uses **`run_js_script`** for guest JS and a frozen tool surface; do not assume **`node`** exists. For **general** in-guest scripting, prefer **`ctx.vfs`** + **`ctx.execLine`** / **`ctx.runBinCommand`** and optional **`ctx.bare.*`** modules when enabled.
|
||||
|
||||
## Writing scripts (`run(ctx, argv)`)
|
||||
|
||||
- **Argv** — `argv` is a string array; **`argv[0]`** is how you were invoked (symlink name matters for multi-call binaries).
|
||||
- **Stdout** — Prefer **`ctx.console.log`** / **`ctx.console.error`** (session-aware). For binary or captured stdout, **`ctx.bareOsBinWrite`** may exist when the shell captures pipeline output.
|
||||
- **Shell a subprocess** — **`await ctx.execLine('some shell line', { signal, timeoutMs })`** returns a string (see booter **`raceWithAbortAndTimeout`**). Heavy work: **`await ctx.runBinCommand(['/bin/grep', …], opts)`** for same resolution as the interactive shell.
|
||||
- **Filesystem** — **`await ctx.vfs.readFile(path)`** → **`Uint8Array`**; **`await ctx.vfs.writeFile(path, buf, opts?)`**. Decode with **`ctx.b4a.toString(buf)`** or **`TextDecoder`**. Always use **absolute** paths under **`/home`**, **`/tmp`**, **`/mnt`**, **`/bin`**, etc., per policy.
|
||||
- **Environment** — **`ctx.env`** is mutable shell state (also **`ctx.vfs.env`**). After **`execLine`**, **`ctx.env.BARE_OS_EXIT_STATUS`** reflects last exit code when the booter sets it.
|
||||
- **Exit** — Set **`ctx.exitCode = 1`** (or other code) on error; **`0`** on success. **`ctx.requestBooterExit(code)`** ends the whole session from builtins like **`exit`**.
|
||||
|
||||
## Building “apps” (long-lived behaviour)
|
||||
|
||||
Think in layers the stock OS already uses:
|
||||
|
||||
| Layer | Mechanism | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG; pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
|
||||
| **Virtual files** | **`bareOsRegisterVirtualFile(name, reader, opts?)`** | Serves **`/run/bare-os/virtual/<name>`**; gated by runtime caps. |
|
||||
| **IPC** | **`ctx.bareOsIpc`** when present | **`push`/`take`**, JSON helpers, fanout, duplex bridge — bounded; audit when **`BARE_OS_IPC_AUDIT=1`**. |
|
||||
| **Kernel extensions** | **`bareOsRegisterKernelExtensionRecord`**, **`bareOsRunImageScript`** under **`/lib/bare-os/extensions/`** | Trusted image paths only. |
|
||||
| **Sandboxed user JS** | **`bareOsSandboxRunScript(source, argv?, opts?)`** | Restricted **`ctx`**; disable with **`BARE_OS_SANDBOX_SCRIPT=0`**. |
|
||||
| **Pear / host** | **`bareOsPearIpcEmit`**, **`bareOsPearIpcRequest`**, mirror/export hints | Host must cooperate; return **`{ ok, hint }`** patterns. |
|
||||
|
||||
Before touching sensitive **`ctx`** methods in hardened images, call **`ctx.bareOsIsCtxMethodAllowed?.(name)`** when boot policy **`BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`** is set.
|
||||
|
||||
## `ctx` field map (cheat sheet)
|
||||
|
||||
**Always read live truth** for capability bits: **`read_proc_file`** on **`/proc/bare_os/features`** and **`/proc/bare_os/capabilities.json`** — do not infer from man pages alone (see **`bare-os-kernel-proc`** skill).
|
||||
|
||||
### Files, drives, process
|
||||
|
||||
- **`ctx.vfs`** — **`readFile`**, **`writeFile`**, **`mkdir`**, **`readdir`**, **`stat`/`lstat`**, **`chmod`**, … Path routing: system vs **personal** Hyperdrive; **`ctx.drive`** vs **`ctx.personalDrive`** for advanced use.
|
||||
- **`ctx.env`**, **`ctx.drive`**, **`ctx.personalDrive`**, **`ctx.disk`** — Session identity and mounts.
|
||||
- **`ctx.execLine`**, **`ctx.runBinCommand`** — Shell and `/bin` execution with shared policy (timeouts, abort).
|
||||
|
||||
### Bytes, console, session
|
||||
|
||||
- **`ctx.b4a`** — Buffer/string helpers for Hyperdrive payloads.
|
||||
- **`ctx.console`**, **`ctx.readLine`**, **`ctx.writeScreen`** — REPL session ( **`readLine`** may be Fish-backed when enabled).
|
||||
- **`ctx.exitCode`**, **`ctx.requestBooterExit`**, **`ctx.registerKernelShutdownHook`**
|
||||
|
||||
### Bare OS introspection & policy
|
||||
|
||||
- **`ctx.bareOsCtxApiVersion`**, **`ctx.bareOsRuntimeCaps`** (frozen)
|
||||
- **`ctx.bareOsAdvertisedKernelCapabilityWords`**, **`ctx.bareOsSeedKernelCapabilityWords`** — **`>>> 0`** when testing bits.
|
||||
- **`ctx.bareOsGetResourceStatus`**, **`ctx.bareOsReadProcMetricsLive`**, **`ctx.bareOsReadBareTopSnapshot`**
|
||||
- **`ctx.bareOsRegisterVirtualFile`**, **`ctx.bareOsInvalidateVirtualFile`**, **`ctx.bareOsUpdateVirtualFileMeta`**
|
||||
- **`ctx.bareOsEmitIpcAudit`**, **`ctx.bareOsEvaluatePeerAdmission`**, **`ctx.bareOsEmitMirrorDriveHint`**
|
||||
|
||||
### Optional / host-dependent
|
||||
|
||||
- **`ctx.httpFetch`** — Same allow/deny policy as **`curl`** / **`wget`**; every host for **`web_fetch`** must be allowlisted.
|
||||
- **`ctx.bare`** — Frozen map of vendored modules (**`b4a`**, **`protomux`**, …) when **`BARE_OS_BARE_MODULES`** allows.
|
||||
- **`ctx.bareOsHostStats`**, **`ctx.bareOsChat*`**, **`ctx.bareOsPearIpc*`** — Present only when wired by the booter/host.
|
||||
|
||||
For the **full** list and semantics, open **`developer-guide/02-the-context-object.md`** in the repo (or **`read_file`** on a mounted checkout).
|
||||
|
||||
## Minimal script template (guest)
|
||||
|
||||
```js
|
||||
/**
|
||||
* @param {Record<string, unknown>} ctx
|
||||
* @param {string[]} argv
|
||||
*/
|
||||
export async function run(ctx, argv) {
|
||||
const argv0 = argv[0] || 'script'
|
||||
const vfs = ctx.vfs
|
||||
if (!vfs?.readFile) {
|
||||
ctx.console.error(argv0 + ': no vfs')
|
||||
ctx.exitCode = 1
|
||||
return
|
||||
}
|
||||
try {
|
||||
const buf = await vfs.readFile('/proc/bare_os/features.json')
|
||||
const t =
|
||||
ctx.b4a && typeof ctx.b4a.toString === 'function'
|
||||
? ctx.b4a.toString(buf)
|
||||
: new TextDecoder().decode(buf)
|
||||
ctx.console.log(t.slice(0, 500))
|
||||
} catch (e) {
|
||||
ctx.console.error(argv0 + ': ' + (e && e.message ? e.message : String(e)))
|
||||
ctx.exitCode = 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Save under **`/home/.../my-tool.mjs`** and run by **absolute path** (or register under **`/bin`** on the image). **Do not** rely on **`node`** in the guest.
|
||||
|
||||
## Agent-specific note
|
||||
|
||||
When helping **inside `/bin/agent`**, the model uses **tools** (`read_file`, `run_js_script`, …) backed by the **same** personal/system VFS as the rest of the guest. **`run_js_script`** writes a temp **`.mjs`** under **`~/.agent/`** and executes it like a **`/bin`** script — the script body should use the same **`ctx`** patterns above when the harness passes **`ctx`**.
|
||||
|
||||
## Checklist before shipping
|
||||
|
||||
1. **`read_proc_file`** / **`get_system_info`** — confirm needed **features** and **caps** exist this session.
|
||||
2. **Paths** — absolute, no **`..`** escape from allowed roots.
|
||||
3. **Timeouts** — pass **`AbortSignal`** / **`timeoutMs`** to **`execLine`** / **`readLine`** for network or slow FS.
|
||||
4. **Teardown** — unregister hooks, clear intervals, dispose IPC fanout subscribers.
|
||||
5. **Secrets** — never log **`~/.agent/config.json`** or keys; redact in **`MEMORY.md`**.
|
||||
|
||||
## Output format (when this skill was used)
|
||||
|
||||
- **What you read** — which **`ctx`** fields or **`/proc`** files grounded the answer.
|
||||
- **Plan** — file paths, entrypoint (`run` vs `start`), and exit semantics.
|
||||
- **Risks** — policy gates, missing caps, host-only APIs.
|
||||
File diff suppressed because one or more lines are too long
@@ -24,7 +24,8 @@ var BARE_AGENT_WORKSPACE_SHARE = '/share/agent-workspace'
|
||||
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-kernel-proc/SKILL.md',
|
||||
'skills/bare-os-super-developer/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`** (P2P / drive health style checks) and **`bare-os-kernel-proc`** (authoritative **`/proc/bare_os/*`** reads vs man-page guessing).
|
||||
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`**).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
+124
@@ -0,0 +1,124 @@
|
||||
---
|
||||
name: bare-os-super-developer
|
||||
version: 1.0.0
|
||||
description: Write Bare OS scripts and small apps using ctx — VFS, execLine, hooks, caps, and safe patterns (no Node in /bin/agent loop).
|
||||
tags: [bare-os, ctx, scripts, vfs, kernel, developer]
|
||||
requires: [read_file, read_proc_file, run_js_script]
|
||||
---
|
||||
|
||||
# bare-os-super-developer — Scripts, apps, and `ctx`
|
||||
|
||||
## When to use
|
||||
|
||||
Use this skill when you (or the user) need to **author or debug** Bare OS **JavaScript** that runs **inside the guest** (kernel init, `/bin/*` utilities, `kernel.ext.d`, user `.mjs` run via **`run_js_script`**, or Pear/booter-hosted scripts). It complements repo docs: treat **`developer-guide/02-the-context-object.md`** and **`packages/bare-os-booter/lib/bare-os-ctx.d.ts`** as the canonical deep dives; this file is the **fast mental model**.
|
||||
|
||||
## Core model
|
||||
|
||||
1. **Entrypoints** — Kernel: **`async function start(ctx)`** in `/boot/init.js` (or your image). Commands: **`async function run(ctx, argv)`** where **`argv[0]`** is the invoked name (e.g. `agent`). You **must** set **`ctx.exitCode`** (number) before returning on failure paths.
|
||||
2. **`ctx` is not Node** — There is no full **`process`**, no **`require('node:fs')`**. The booter assembles **`ctx`** as the narrow **syscall surface**: **`vfs`**, **`env`**, **`execLine`**, **`runBinCommand`**, optional **`httpFetch`**, **`bare`**, identity helpers, diagnostics, etc. See the mermaid overview in Chapter 2 of the developer guide.
|
||||
3. **`/bin/agent` is special** — The agent bundle uses **`run_js_script`** for guest JS and a frozen tool surface; do not assume **`node`** exists. For **general** in-guest scripting, prefer **`ctx.vfs`** + **`ctx.execLine`** / **`ctx.runBinCommand`** and optional **`ctx.bare.*`** modules when enabled.
|
||||
|
||||
## Writing scripts (`run(ctx, argv)`)
|
||||
|
||||
- **Argv** — `argv` is a string array; **`argv[0]`** is how you were invoked (symlink name matters for multi-call binaries).
|
||||
- **Stdout** — Prefer **`ctx.console.log`** / **`ctx.console.error`** (session-aware). For binary or captured stdout, **`ctx.bareOsBinWrite`** may exist when the shell captures pipeline output.
|
||||
- **Shell a subprocess** — **`await ctx.execLine('some shell line', { signal, timeoutMs })`** returns a string (see booter **`raceWithAbortAndTimeout`**). Heavy work: **`await ctx.runBinCommand(['/bin/grep', …], opts)`** for same resolution as the interactive shell.
|
||||
- **Filesystem** — **`await ctx.vfs.readFile(path)`** → **`Uint8Array`**; **`await ctx.vfs.writeFile(path, buf, opts?)`**. Decode with **`ctx.b4a.toString(buf)`** or **`TextDecoder`**. Always use **absolute** paths under **`/home`**, **`/tmp`**, **`/mnt`**, **`/bin`**, etc., per policy.
|
||||
- **Environment** — **`ctx.env`** is mutable shell state (also **`ctx.vfs.env`**). After **`execLine`**, **`ctx.env.BARE_OS_EXIT_STATUS`** reflects last exit code when the booter sets it.
|
||||
- **Exit** — Set **`ctx.exitCode = 1`** (or other code) on error; **`0`** on success. **`ctx.requestBooterExit(code)`** ends the whole session from builtins like **`exit`**.
|
||||
|
||||
## Building “apps” (long-lived behaviour)
|
||||
|
||||
Think in layers the stock OS already uses:
|
||||
|
||||
| Layer | Mechanism | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG; pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
|
||||
| **Virtual files** | **`bareOsRegisterVirtualFile(name, reader, opts?)`** | Serves **`/run/bare-os/virtual/<name>`**; gated by runtime caps. |
|
||||
| **IPC** | **`ctx.bareOsIpc`** when present | **`push`/`take`**, JSON helpers, fanout, duplex bridge — bounded; audit when **`BARE_OS_IPC_AUDIT=1`**. |
|
||||
| **Kernel extensions** | **`bareOsRegisterKernelExtensionRecord`**, **`bareOsRunImageScript`** under **`/lib/bare-os/extensions/`** | Trusted image paths only. |
|
||||
| **Sandboxed user JS** | **`bareOsSandboxRunScript(source, argv?, opts?)`** | Restricted **`ctx`**; disable with **`BARE_OS_SANDBOX_SCRIPT=0`**. |
|
||||
| **Pear / host** | **`bareOsPearIpcEmit`**, **`bareOsPearIpcRequest`**, mirror/export hints | Host must cooperate; return **`{ ok, hint }`** patterns. |
|
||||
|
||||
Before touching sensitive **`ctx`** methods in hardened images, call **`ctx.bareOsIsCtxMethodAllowed?.(name)`** when boot policy **`BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`** is set.
|
||||
|
||||
## `ctx` field map (cheat sheet)
|
||||
|
||||
**Always read live truth** for capability bits: **`read_proc_file`** on **`/proc/bare_os/features`** and **`/proc/bare_os/capabilities.json`** — do not infer from man pages alone (see **`bare-os-kernel-proc`** skill).
|
||||
|
||||
### Files, drives, process
|
||||
|
||||
- **`ctx.vfs`** — **`readFile`**, **`writeFile`**, **`mkdir`**, **`readdir`**, **`stat`/`lstat`**, **`chmod`**, … Path routing: system vs **personal** Hyperdrive; **`ctx.drive`** vs **`ctx.personalDrive`** for advanced use.
|
||||
- **`ctx.env`**, **`ctx.drive`**, **`ctx.personalDrive`**, **`ctx.disk`** — Session identity and mounts.
|
||||
- **`ctx.execLine`**, **`ctx.runBinCommand`** — Shell and `/bin` execution with shared policy (timeouts, abort).
|
||||
|
||||
### Bytes, console, session
|
||||
|
||||
- **`ctx.b4a`** — Buffer/string helpers for Hyperdrive payloads.
|
||||
- **`ctx.console`**, **`ctx.readLine`**, **`ctx.writeScreen`** — REPL session ( **`readLine`** may be Fish-backed when enabled).
|
||||
- **`ctx.exitCode`**, **`ctx.requestBooterExit`**, **`ctx.registerKernelShutdownHook`**
|
||||
|
||||
### Bare OS introspection & policy
|
||||
|
||||
- **`ctx.bareOsCtxApiVersion`**, **`ctx.bareOsRuntimeCaps`** (frozen)
|
||||
- **`ctx.bareOsAdvertisedKernelCapabilityWords`**, **`ctx.bareOsSeedKernelCapabilityWords`** — **`>>> 0`** when testing bits.
|
||||
- **`ctx.bareOsGetResourceStatus`**, **`ctx.bareOsReadProcMetricsLive`**, **`ctx.bareOsReadBareTopSnapshot`**
|
||||
- **`ctx.bareOsRegisterVirtualFile`**, **`ctx.bareOsInvalidateVirtualFile`**, **`ctx.bareOsUpdateVirtualFileMeta`**
|
||||
- **`ctx.bareOsEmitIpcAudit`**, **`ctx.bareOsEvaluatePeerAdmission`**, **`ctx.bareOsEmitMirrorDriveHint`**
|
||||
|
||||
### Optional / host-dependent
|
||||
|
||||
- **`ctx.httpFetch`** — Same allow/deny policy as **`curl`** / **`wget`**; every host for **`web_fetch`** must be allowlisted.
|
||||
- **`ctx.bare`** — Frozen map of vendored modules (**`b4a`**, **`protomux`**, …) when **`BARE_OS_BARE_MODULES`** allows.
|
||||
- **`ctx.bareOsHostStats`**, **`ctx.bareOsChat*`**, **`ctx.bareOsPearIpc*`** — Present only when wired by the booter/host.
|
||||
|
||||
For the **full** list and semantics, open **`developer-guide/02-the-context-object.md`** in the repo (or **`read_file`** on a mounted checkout).
|
||||
|
||||
## Minimal script template (guest)
|
||||
|
||||
```js
|
||||
/**
|
||||
* @param {Record<string, unknown>} ctx
|
||||
* @param {string[]} argv
|
||||
*/
|
||||
export async function run(ctx, argv) {
|
||||
const argv0 = argv[0] || 'script'
|
||||
const vfs = ctx.vfs
|
||||
if (!vfs?.readFile) {
|
||||
ctx.console.error(argv0 + ': no vfs')
|
||||
ctx.exitCode = 1
|
||||
return
|
||||
}
|
||||
try {
|
||||
const buf = await vfs.readFile('/proc/bare_os/features.json')
|
||||
const t =
|
||||
ctx.b4a && typeof ctx.b4a.toString === 'function'
|
||||
? ctx.b4a.toString(buf)
|
||||
: new TextDecoder().decode(buf)
|
||||
ctx.console.log(t.slice(0, 500))
|
||||
} catch (e) {
|
||||
ctx.console.error(argv0 + ': ' + (e && e.message ? e.message : String(e)))
|
||||
ctx.exitCode = 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Save under **`/home/.../my-tool.mjs`** and run by **absolute path** (or register under **`/bin`** on the image). **Do not** rely on **`node`** in the guest.
|
||||
|
||||
## Agent-specific note
|
||||
|
||||
When helping **inside `/bin/agent`**, the model uses **tools** (`read_file`, `run_js_script`, …) backed by the **same** personal/system VFS as the rest of the guest. **`run_js_script`** writes a temp **`.mjs`** under **`~/.agent/`** and executes it like a **`/bin`** script — the script body should use the same **`ctx`** patterns above when the harness passes **`ctx`**.
|
||||
|
||||
## Checklist before shipping
|
||||
|
||||
1. **`read_proc_file`** / **`get_system_info`** — confirm needed **features** and **caps** exist this session.
|
||||
2. **Paths** — absolute, no **`..`** escape from allowed roots.
|
||||
3. **Timeouts** — pass **`AbortSignal`** / **`timeoutMs`** to **`execLine`** / **`readLine`** for network or slow FS.
|
||||
4. **Teardown** — unregister hooks, clear intervals, dispose IPC fanout subscribers.
|
||||
5. **Secrets** — never log **`~/.agent/config.json`** or keys; redact in **`MEMORY.md`**.
|
||||
|
||||
## Output format (when this skill was used)
|
||||
|
||||
- **What you read** — which **`ctx`** fields or **`/proc`** files grounded the answer.
|
||||
- **Plan** — file paths, entrypoint (`run` vs `start`), and exit semantics.
|
||||
- **Risks** — policy gates, missing caps, host-only APIs.
|
||||
@@ -116,6 +116,7 @@ test('bareAgentEnsureSkillTemplates copies skill seeds when missing', async (t)
|
||||
set('/share/agent-workspace/skills/.gitkeep', '')
|
||||
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/skill-loader.stub.js', '// stub')
|
||||
const vfs = {
|
||||
async mkdir(_p, _o) {},
|
||||
@@ -144,6 +145,7 @@ 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/skill-loader.js'))
|
||||
})
|
||||
|
||||
|
||||
@@ -1490,7 +1490,8 @@ var BARE_AGENT_WORKSPACE_SHARE = '/share/agent-workspace'
|
||||
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-kernel-proc/SKILL.md',
|
||||
'skills/bare-os-super-developer/SKILL.md'
|
||||
])
|
||||
|
||||
/**
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"schema": 2,
|
||||
"profileId": "bare-os-posix-like",
|
||||
"generatedAt": "2026-04-22T07:06:59.998Z",
|
||||
"generatedAt": "2026-04-22T07:14:40.458Z",
|
||||
"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": 1776841619998,
|
||||
"atMs": 1776842080458,
|
||||
"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`** (P2P / drive health style checks) and **`bare-os-kernel-proc`** (authoritative **`/proc/bare_os/*`** reads vs man-page guessing).
|
||||
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`**).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
+124
@@ -0,0 +1,124 @@
|
||||
---
|
||||
name: bare-os-super-developer
|
||||
version: 1.0.0
|
||||
description: Write Bare OS scripts and small apps using ctx — VFS, execLine, hooks, caps, and safe patterns (no Node in /bin/agent loop).
|
||||
tags: [bare-os, ctx, scripts, vfs, kernel, developer]
|
||||
requires: [read_file, read_proc_file, run_js_script]
|
||||
---
|
||||
|
||||
# bare-os-super-developer — Scripts, apps, and `ctx`
|
||||
|
||||
## When to use
|
||||
|
||||
Use this skill when you (or the user) need to **author or debug** Bare OS **JavaScript** that runs **inside the guest** (kernel init, `/bin/*` utilities, `kernel.ext.d`, user `.mjs` run via **`run_js_script`**, or Pear/booter-hosted scripts). It complements repo docs: treat **`developer-guide/02-the-context-object.md`** and **`packages/bare-os-booter/lib/bare-os-ctx.d.ts`** as the canonical deep dives; this file is the **fast mental model**.
|
||||
|
||||
## Core model
|
||||
|
||||
1. **Entrypoints** — Kernel: **`async function start(ctx)`** in `/boot/init.js` (or your image). Commands: **`async function run(ctx, argv)`** where **`argv[0]`** is the invoked name (e.g. `agent`). You **must** set **`ctx.exitCode`** (number) before returning on failure paths.
|
||||
2. **`ctx` is not Node** — There is no full **`process`**, no **`require('node:fs')`**. The booter assembles **`ctx`** as the narrow **syscall surface**: **`vfs`**, **`env`**, **`execLine`**, **`runBinCommand`**, optional **`httpFetch`**, **`bare`**, identity helpers, diagnostics, etc. See the mermaid overview in Chapter 2 of the developer guide.
|
||||
3. **`/bin/agent` is special** — The agent bundle uses **`run_js_script`** for guest JS and a frozen tool surface; do not assume **`node`** exists. For **general** in-guest scripting, prefer **`ctx.vfs`** + **`ctx.execLine`** / **`ctx.runBinCommand`** and optional **`ctx.bare.*`** modules when enabled.
|
||||
|
||||
## Writing scripts (`run(ctx, argv)`)
|
||||
|
||||
- **Argv** — `argv` is a string array; **`argv[0]`** is how you were invoked (symlink name matters for multi-call binaries).
|
||||
- **Stdout** — Prefer **`ctx.console.log`** / **`ctx.console.error`** (session-aware). For binary or captured stdout, **`ctx.bareOsBinWrite`** may exist when the shell captures pipeline output.
|
||||
- **Shell a subprocess** — **`await ctx.execLine('some shell line', { signal, timeoutMs })`** returns a string (see booter **`raceWithAbortAndTimeout`**). Heavy work: **`await ctx.runBinCommand(['/bin/grep', …], opts)`** for same resolution as the interactive shell.
|
||||
- **Filesystem** — **`await ctx.vfs.readFile(path)`** → **`Uint8Array`**; **`await ctx.vfs.writeFile(path, buf, opts?)`**. Decode with **`ctx.b4a.toString(buf)`** or **`TextDecoder`**. Always use **absolute** paths under **`/home`**, **`/tmp`**, **`/mnt`**, **`/bin`**, etc., per policy.
|
||||
- **Environment** — **`ctx.env`** is mutable shell state (also **`ctx.vfs.env`**). After **`execLine`**, **`ctx.env.BARE_OS_EXIT_STATUS`** reflects last exit code when the booter sets it.
|
||||
- **Exit** — Set **`ctx.exitCode = 1`** (or other code) on error; **`0`** on success. **`ctx.requestBooterExit(code)`** ends the whole session from builtins like **`exit`**.
|
||||
|
||||
## Building “apps” (long-lived behaviour)
|
||||
|
||||
Think in layers the stock OS already uses:
|
||||
|
||||
| Layer | Mechanism | Notes |
|
||||
| --- | --- | --- |
|
||||
| **Init** | **`bareOsRegisterBootStepHook`**, initd units | Boot-order DAG; pair **`registerKernelShutdownHook`** / initd disposers for teardown. |
|
||||
| **Virtual files** | **`bareOsRegisterVirtualFile(name, reader, opts?)`** | Serves **`/run/bare-os/virtual/<name>`**; gated by runtime caps. |
|
||||
| **IPC** | **`ctx.bareOsIpc`** when present | **`push`/`take`**, JSON helpers, fanout, duplex bridge — bounded; audit when **`BARE_OS_IPC_AUDIT=1`**. |
|
||||
| **Kernel extensions** | **`bareOsRegisterKernelExtensionRecord`**, **`bareOsRunImageScript`** under **`/lib/bare-os/extensions/`** | Trusted image paths only. |
|
||||
| **Sandboxed user JS** | **`bareOsSandboxRunScript(source, argv?, opts?)`** | Restricted **`ctx`**; disable with **`BARE_OS_SANDBOX_SCRIPT=0`**. |
|
||||
| **Pear / host** | **`bareOsPearIpcEmit`**, **`bareOsPearIpcRequest`**, mirror/export hints | Host must cooperate; return **`{ ok, hint }`** patterns. |
|
||||
|
||||
Before touching sensitive **`ctx`** methods in hardened images, call **`ctx.bareOsIsCtxMethodAllowed?.(name)`** when boot policy **`BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`** is set.
|
||||
|
||||
## `ctx` field map (cheat sheet)
|
||||
|
||||
**Always read live truth** for capability bits: **`read_proc_file`** on **`/proc/bare_os/features`** and **`/proc/bare_os/capabilities.json`** — do not infer from man pages alone (see **`bare-os-kernel-proc`** skill).
|
||||
|
||||
### Files, drives, process
|
||||
|
||||
- **`ctx.vfs`** — **`readFile`**, **`writeFile`**, **`mkdir`**, **`readdir`**, **`stat`/`lstat`**, **`chmod`**, … Path routing: system vs **personal** Hyperdrive; **`ctx.drive`** vs **`ctx.personalDrive`** for advanced use.
|
||||
- **`ctx.env`**, **`ctx.drive`**, **`ctx.personalDrive`**, **`ctx.disk`** — Session identity and mounts.
|
||||
- **`ctx.execLine`**, **`ctx.runBinCommand`** — Shell and `/bin` execution with shared policy (timeouts, abort).
|
||||
|
||||
### Bytes, console, session
|
||||
|
||||
- **`ctx.b4a`** — Buffer/string helpers for Hyperdrive payloads.
|
||||
- **`ctx.console`**, **`ctx.readLine`**, **`ctx.writeScreen`** — REPL session ( **`readLine`** may be Fish-backed when enabled).
|
||||
- **`ctx.exitCode`**, **`ctx.requestBooterExit`**, **`ctx.registerKernelShutdownHook`**
|
||||
|
||||
### Bare OS introspection & policy
|
||||
|
||||
- **`ctx.bareOsCtxApiVersion`**, **`ctx.bareOsRuntimeCaps`** (frozen)
|
||||
- **`ctx.bareOsAdvertisedKernelCapabilityWords`**, **`ctx.bareOsSeedKernelCapabilityWords`** — **`>>> 0`** when testing bits.
|
||||
- **`ctx.bareOsGetResourceStatus`**, **`ctx.bareOsReadProcMetricsLive`**, **`ctx.bareOsReadBareTopSnapshot`**
|
||||
- **`ctx.bareOsRegisterVirtualFile`**, **`ctx.bareOsInvalidateVirtualFile`**, **`ctx.bareOsUpdateVirtualFileMeta`**
|
||||
- **`ctx.bareOsEmitIpcAudit`**, **`ctx.bareOsEvaluatePeerAdmission`**, **`ctx.bareOsEmitMirrorDriveHint`**
|
||||
|
||||
### Optional / host-dependent
|
||||
|
||||
- **`ctx.httpFetch`** — Same allow/deny policy as **`curl`** / **`wget`**; every host for **`web_fetch`** must be allowlisted.
|
||||
- **`ctx.bare`** — Frozen map of vendored modules (**`b4a`**, **`protomux`**, …) when **`BARE_OS_BARE_MODULES`** allows.
|
||||
- **`ctx.bareOsHostStats`**, **`ctx.bareOsChat*`**, **`ctx.bareOsPearIpc*`** — Present only when wired by the booter/host.
|
||||
|
||||
For the **full** list and semantics, open **`developer-guide/02-the-context-object.md`** in the repo (or **`read_file`** on a mounted checkout).
|
||||
|
||||
## Minimal script template (guest)
|
||||
|
||||
```js
|
||||
/**
|
||||
* @param {Record<string, unknown>} ctx
|
||||
* @param {string[]} argv
|
||||
*/
|
||||
export async function run(ctx, argv) {
|
||||
const argv0 = argv[0] || 'script'
|
||||
const vfs = ctx.vfs
|
||||
if (!vfs?.readFile) {
|
||||
ctx.console.error(argv0 + ': no vfs')
|
||||
ctx.exitCode = 1
|
||||
return
|
||||
}
|
||||
try {
|
||||
const buf = await vfs.readFile('/proc/bare_os/features.json')
|
||||
const t =
|
||||
ctx.b4a && typeof ctx.b4a.toString === 'function'
|
||||
? ctx.b4a.toString(buf)
|
||||
: new TextDecoder().decode(buf)
|
||||
ctx.console.log(t.slice(0, 500))
|
||||
} catch (e) {
|
||||
ctx.console.error(argv0 + ': ' + (e && e.message ? e.message : String(e)))
|
||||
ctx.exitCode = 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Save under **`/home/.../my-tool.mjs`** and run by **absolute path** (or register under **`/bin`** on the image). **Do not** rely on **`node`** in the guest.
|
||||
|
||||
## Agent-specific note
|
||||
|
||||
When helping **inside `/bin/agent`**, the model uses **tools** (`read_file`, `run_js_script`, …) backed by the **same** personal/system VFS as the rest of the guest. **`run_js_script`** writes a temp **`.mjs`** under **`~/.agent/`** and executes it like a **`/bin`** script — the script body should use the same **`ctx`** patterns above when the harness passes **`ctx`**.
|
||||
|
||||
## Checklist before shipping
|
||||
|
||||
1. **`read_proc_file`** / **`get_system_info`** — confirm needed **features** and **caps** exist this session.
|
||||
2. **Paths** — absolute, no **`..`** escape from allowed roots.
|
||||
3. **Timeouts** — pass **`AbortSignal`** / **`timeoutMs`** to **`execLine`** / **`readLine`** for network or slow FS.
|
||||
4. **Teardown** — unregister hooks, clear intervals, dispose IPC fanout subscribers.
|
||||
5. **Secrets** — never log **`~/.agent/config.json`** or keys; redact in **`MEMORY.md`**.
|
||||
|
||||
## Output format (when this skill was used)
|
||||
|
||||
- **What you read** — which **`ctx`** fields or **`/proc`** files grounded the answer.
|
||||
- **Plan** — file paths, entrypoint (`run` vs `start`), and exit semantics.
|
||||
- **Risks** — policy gates, missing caps, host-only APIs.
|
||||
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user