lousho add installs a tool, skill, channel, schedule, memory slot or kit into an
agent directory from a registry. A kit item is a
whole agent directory: installing it lays out agent.*, instructions.md,
tools, skills and sub-agents so the target becomes (or grows into) an agent
directory itself. A registry is plain
static JSON: an index plus one document per item that carries the file contents.
The files are copied into your project as source you own and can edit. There is
no runtime plugin loader, and nothing from a registry is executed or imported
while adding it.
lousho add works out of the box: without --registry or LOUSHO_REGISTRY it
reads the default registry at https://registry.lousho.com/index.json, which
is the registry/dist/ folder of the SDK’s repository served as static JSON.
When that host cannot be reached, lousho add reads the same committed folder
from GitHub instead: the release tag of the installed SDK version
(https://raw.githubusercontent.com/LinuxDevil/lousho/<version>/registry/dist/index.json),
then the same tag with a v prefix (older releases), then main.
If GitHub cannot be reached either (offline, an outage, a version whose tag was
never pushed), lousho add reads the copy of registry/dist/ that ships inside
the installed package and prints a one-line notice that this bundled registry
may be older than the online one. Only the default falls back, never a registry you named.
--registry and LOUSHO_REGISTRY point it at another registry, and the value
none (in either place) disables the registry entirely — lousho add then
fails with LOUSHO_CONFIG_INVALID, for offline or locked-down use.
The default registry currently carries nine items:
The coding kits (
coding-kit, coding-pi) use the agent directory itself as
the project workspace. Their file tools therefore refuse to change the
agent’s own files: agent.*, approve.*, hooks.*, instructions*,
lousho-registry.json, and anything under .lousho/, tools/, skills/,
subagents/, .git/ and node_modules/. Their shell runs only node --test
(test file paths, no flags) and git status. The kits still run the tests the
agent writes code for, so the agent’s code runs as your user. Use a sandboxed
shell for untrusted work (see Workspace tools). The
coding-pi kit’s Pi coder sub-agent has its own tools, and these rules do not
cover them.
Before it writes anything,
lousho add prints the permission manifest and the
files it will write, checks the item’s code against the manifest, then asks
[y/N]. After writing, it records the item in lousho-registry.json.
Format
The index is{ items: [{ name, type, description, url | path }] }. type is
tool, skill, channel, schedule, memory or kit. url / path locate the
item document; a relative one is resolved against the index’s own location.
Each item document is:
index.json:
name and type must match its index entry, and a
name starts with a letter or digit, followed by letters, digits, ., _ and
-. A document that does not match the
format is LOUSHO_REGISTRY_INVALID, with the fields named.
To contribute an item to the default registry, add a registry/<name>/ folder
to the SDK’s repository: an item.json (name, type, description,
permissions, dependencies) and the item’s files laid out the way they
should land in the agent directory (tools/x.ts, skills/<name>/SKILL.md,
channels/x.ts; a kit’s files make up a whole agent directory, e.g.
agent.json, instructions.md, hooks.ts, tools/, subagents/<name>/).
npm run registry:build validates every item against the
same rules lousho add enforces (schema, paths, the code/manifest check) and
rebuilds registry/dist/; commit the result. CI runs npm run registry:check,
which fails when registry/dist/ is stale.
Permission manifest
permissions declares what the item can do, so you can decide before you
install it. All of it is optional; what is missing is shown as “none” / “no”.
What
lousho add enforces, before it writes anything:
-
The code matches the manifest. Every JavaScript and TypeScript file of the
item is scanned, with comments stripped, for what it visibly reaches for:
exec: truefor an import ofchild_process(with or withoutnode:),execaorshelljs, or a use of the SDK’screateShellTool,runShellCommandorSubprocessSandbox;filesystem: "read"(or"write") for an import offs(includingfs/promisesand thenode:forms),fs-extraorgraceful-fs, or the SDK’screateFsTools, and"write"for a call towriteFile,appendFile,createWriteStream,mkdir,mkdtemp,rm,rmdir,unlink,rename,copyFileorcp(and theirSyncforms);- a non-empty
networkforfetch(, a use of the SDK’screateHttpTool, or an import ofhttp,https,http2,net,tls,dgram,undici,axios,node-fetchorws, and everyhttp(s)://orws(s)://host in a string must match anetworkentry (a host built at run time, such as`https://${host}/`, needs a non-emptynetworkand is printed as a note, since it cannot be checked); - every
process.env.NAMEandprocess.env['NAME']must be listed inenv.
eval(,new Function(, a computedprocess.env[name],process.envused as a whole, animport()orrequire()of anything but a string literal, andrequireused as a value (const r = require) are always refused. A mismatch isLOUSHO_REGISTRY_MANIFEST_MISMATCHwith every finding as<file>:<line>: <what> (<fix>);--dry-runreports it too. Markdown and other files that are not code (a skill’sSKILL.md) are not scanned.networkentries must be host names or*.wildcards (api.example.com,*.example.com— a wildcard matches subdomains only, not the bare host) andenventries variable names (SEARCH_KEY); anything else isLOUSHO_REGISTRY_INVALID. -
Consent covers the elevated permissions.
exec: true,filesystem: "write", a non-emptynetworkand a non-emptyenvare marked[elevated: ...]in the printed manifest. The interactive prompt lists them before[y/N]. With--yeseach one must be named in--allow(--allow network,envfor the example above), because--yesis how scripts and agents runlousho addand should not grant command execution silently. -
A receipt of what was installed. After writing,
lousho addupdateslousho-registry.jsonat the root of the agent directory (next toinstructions.md). Each item’s entry has itstype, theregistryit came from,installedAt, thepermissionsand every file’spathandsha256, so you can tell later whether a file was edited.--overwritereplaces the entry;--dry-runwrites nothing. A receipt that is not valid JSON stops the install before any file is written. The receipt is whatloadAgentDirenforces at load and run time (below).
loadAgentDir enforces, from the receipt, when the agent loads and the
item’s tools run:
- Integrity. Every file the receipt lists is re-hashed. A file that was
edited or removed since makes its item unattested: a warning names the item
and the changed files, and
resolveAgentDir()reports the same inmanifest.registry(status: 'attested' | 'unattested', plus themodifiedandmissingpaths). Loading is not refused - the files are yours to edit - and an unreadable receipt is a warning, not an error. - Approval. The tools of an item declaring
exec: trueorneedsApproval: true- and of any unattested item, whose stale receipt no longer certifies the modified code - always wait for approval; adenyfrom the tool’s ownneedsApprovalstill denies. Nothing in the agent directory can waive it: anallowpermission rule and a permission mode (acceptEdits) do not run the call (adenyrule,planordontAskstill refuses it), and the directory’s ownapprovefile defers it. Only a person resolving the pause (agent.approvals.resolve()) or anapprovecallback your code passes toloadAgentDir(dir, { approve })decides it. - Sub-agents. A sub-agent directory inside the installed item (a kit’s
subagents/<name>/) is held to the same receipt: its tools are confined like the item’s other tools, and its ownapprovefile defers their enforced calls too. A sub-agent’s pause has noapprovals.resolve()handle, so theapprovecallback your code passes toloadAgentDir()decides them; without one the delegated call does not run, and the lead is told that the sub-agent stopped for an approval. - Network. While a receipt item’s tool runs,
fetchis limited to the hosts itsnetworkdeclares: a host the manifest does not list is refused, and an item that declares nonetworkcannot fetch at all. - Environment. While it runs,
process.envshows the tool only the namesenvdeclares. - Sandboxed tools. A
requiresSandboxtool gets a narrowed adapter:run()is refused withoutexec,writeFile()withoutfilesystem: "write", and a command’s environment is the usual non-secret base plus the declared variables only.
lousho add <name> --overwrite installs the
current files and attests them again.
What it does not do: the install-time check reads the code as written, and the
run-time confinement covers only what the SDK can intercept - calls to fetch
and process.env reads made while the tool runs, and the adapter handed to a
sandboxed tool. Requests through http/net/axios, file access, a reference
captured at module scope (const f = fetch), work done when the file is
imported, and a container’s own network policy (SubprocessSandbox’s
{ allow } is a property of the sandbox, not of the item) are all outside it;
so is code that hides what it does (string escapes, aliasing, encoded
payloads, a dependency that does the work) from the static check. Read the
files it lists (--dry-run shows them) the way you would read any dependency
before running it.
Safety rules
- Every
files[].pathmust be relative, normalized and forward-slashed: no.., no absolute path, no drive letter (C:), no backslashes, no empty or.segments. After resolving symlinks it must still be inside the agent directory, and a symlink target is never written through. - A file must be inside the folder its item’s type allows:
toolintools/,skillinskills/<name>/,channelinchannels/,scheduleinschedules/,memoryinmemory/. Akitis the one exception: as a whole agent directory its files may sit at any relative path (still normalized and inside the target, per the rule above). - Existing files are not overwritten without
--overwrite. All files are checked before any is written, so a bad item writes nothing. Each of these failures isLOUSHO_REGISTRY_UNSAFE_PATHorLOUSHO_REGISTRY_FILE_EXISTS. - A file is at most 256 KiB and an item at most 1 MiB; a registry document at most 2 million characters.
- Only
http(s)URLs and local paths are read, with a 15 second timeout per fetch (LOUSHO_REGISTRY_UNREACHABLEotherwise). dependenciesare printed as annpm install ...line for you to run. The command never installs packages.