The agent had no way to know its container ships ffmpeg, ripgrep or
tesseract, so it either declined work it could do or spent a round finding
out. This adds a command list to the system prompt as a **discovery hint** —
explicitly not an inventory.
Every decision follows from it being a hint:
- The allowlist (~35 entries, `container/commands.rs`) is the curation; a
full PATH dump is 800 entries of coreutils noise. The probe exists so the
list cannot *lie*, not so it can discover: `command -v` at login means we
never announce something a container recreate threw away.
- The rendered prose says the list is partial and names `command -v`, so a
tool outside the allowlist costs one check rather than a wrong conclusion.
An empty probe renders as an explicit "could not be read", never as
silence under a heading promising a list.
- Order is the allowlist's own, grouped by kind of work — the grouping is
the curation, and the reader is a model, not a grep.
- Staleness is cheap both ways, so there is no invalidation machinery: a
login-time snapshot on `UserContext`, non-fatal, refreshed at next login.
The gate is the tool, not the sentinel. Every AGENT.md carries
`common/sandbox.md` — the four system agents included — and the section is
emitted iff the turn's model is shown `execute_cmd`, derived from
`allow_tools` plus the security group's visibility filter for a root turn
and from `child_defs` for a sub-agent: always the same definitions the model
will see. `has_execute_cmd` therefore joins the PrefixCache key, since the
group is switchable mid-conversation and that switch already rewrites the
tool payload in the same provider cache.
The fragment holds only the heading and one stable sentence; every
conditional claim lives in the renderer, because prose promising
`sudo apt-get install` is not the renderer's to retract when the tool is
absent. `execute_cmd`'s own description loses `(python + node available)`:
its job is steering away from the shell, and a capability advertisement
diluted it.
Per blueprint/skill-project.md: the old single-namespace, hand-maintained
index is gone, replaced by a read-only, two-scope tree whose index is a
runtime function of its content.
- skills/ index generated at runtime (crates/skald-core/src/skills/:
inventory, install, validate, watch), injected through the new
<!-- SKILLS_LIST --> placeholder in AGENT.md (agents/common/skills.md);
meta.json inject_skills flag removed. 11 chat/task agents carry the
include, the 4 system agents do not.
- Two trees, both read-only in both directions: skills/shared/{id} (the
group's) and skills/{username}/{id} (one member's own, on the stable
userid). The root is closed too: UserFs::SkillMounts + RouteError (alias
probe, plain-denied paths, no home fallback) and a per-user
.skills-root/{userid} container mount with the two scope mounts nested
inside, plus the fifth self-heal axis (skills_mounted).
- Agent verbs: skill_register/skill_delete (Config group, global scope
behind the new skill.manage capability), fetch_repo for public repos,
list_items(type="skills"); reads are plain read_file on the printed
path. Seeded @fs_read skills/* allow.
- Freshness: a digest-gated watcher on the two trees emits
SystemEvent::SkillsChanged, whose subscriber rebuilds the frozen prompt
prefix via Skald::invalidate_prompt_prefix; in-process writers invalidate
directly.
- The build ships no skills: the three bundled skills (ics2json,
mcp-builder, skill-creator) and skills/index.md are removed, skills/ is
instance data (gitignored, not packaged, no longer pruned by update.sh).
- Docs: skills.md, agents.md, shared-folders.md added; docs/index.md and
agents/README.md updated.
python3 >= 3.12 is increasingly a hard floor for PyPI packages a connector
pulls (mcp-server-linkedin declares `requires-python >=3.12,<3.15`), and
`install::ensure_installed` runs the deps install as a plain `python3 -m pip`,
so the system interpreter is what every python connector builds against.
Trixie ships 3.13; it also moves node 18 -> 20 and tesseract 5.3 -> 5.5.
Adds the shared libraries a headless Chromium links against, for connectors
driving a real browser. Libs only — the browser binary is not baked in, the
connector downloads its own pinned build under its connector dir. That split
is the point: a pip/npm install can fetch a binary but cannot supply system
libs, so these are the genuinely non-self-recoverable half. The list is
patchright's own nativeDeps table for debian13; the `t64` suffixes are Debian
13's 64-bit time_t transition and are not optional.
IMAGE_TAG -> v4 so existing containers are recreated, not just new ones.
Two changes to what a turn costs and what it can see.
## The system prefix is frozen per conversation
`AgentSystemContext::system_context` is called once per round and reassembled
`base` from disk and SQLite each time, so an agent writing `user-memory/index.md`
in round 3 turned round 4 — seconds later, with the provider cache certainly
warm — into a full miss. `base` is the head of every provider's cache key, so it
is the most expensive string in the request to touch.
`PrefixCache` builds it once per (conversation, agent) and holds it on
`UserLoopRuntime`. The refresh rule is the only free one: rebuild once the
conversation has been idle longer than a provider's cache could survive
(20 min). The clock is idle time of the conversation, not time since a file
changed, and reading restarts it — every get is a request about to go out.
Writes are deliberately not reacted to. The agent's own edits are already in the
context, two messages downstream. A write from elsewhere is invisible until the
TTL: that is precisely where an immediate rebuild costs the most, and the
cheaper freshness path already exists — a `read_file` result appends, and
appending invalidates nothing. The injection header now says so.
Also removes 4 DB queries and 2 file reads per round.
## The security boundary is the container, not the mounted subtree
`read_file /tmp/cv.txt` answered "path escapes your workspace" and the agent
re-read the file with `cat`. It was right to refuse — /tmp exists only inside
the container — but the refusal protected nothing: `execute_cmd` already runs
there with passwordless sudo. The mount is the fast path, not the perimeter.
`resolve_target` now routes an absolute path through `container_to_agent`
first. Landing on a mount takes the host path, which also fixes a real bug:
`/root/x` IS `~/x`, yet every tool rejected it, because `PathBuf::join` with an
absolute tail discards the base and the result then failed the prefix check
(`/root/shared/{X}/…` too). Landing nowhere means container-only, served by the
new `container::exec_fs` over `docker exec`, with paths passed positionally so
a path containing `$(…)` stays data. Membership still holds: `/root/shared/{X}`
for a non-member fails exactly as `shared/{X}` does.
Single-file tools get this without a second implementation: `fs::Shuttle` pulls
the file out, runs the unchanged tool on the copy, and pushes it back if the
bytes changed. `list_files` lists in place, `read_file` reads container paths as
text (a shuttled copy cannot back a MediaRef), and `grep_files` refuses them
with a pointer to `rg` rather than approximating its own semantics. The viewer
follows the same routing, so the user can open what the agent read.
Host containment is untouched and still guards every mounted path — it is the
defence against a symlink planted in the container pointing at the host's /etc,
and the container branch never touches the host filesystem at all.
Verified end-to-end against a live skald-runtime:v3 container: write/read/edit
on /tmp round-trip, /etc/os-release reads, binary and shell-metacharacter paths
survive, and /root/notes.md lands in the host home.
`user-memory/` and `shared-memory/` live in SQLite, so nothing of them existed on
disk — and that nothing was worse than it looks. `cat user-memory/x.md` returned a
bare ENOENT, which a model reads as "the note is missing" rather than "wrong door";
and `mkdir -p user-memory && echo … > user-memory/x.md` *succeeded*, writing a real
file into the home that no reader ever visits (every reader goes to `memory_docs`)
and that the next `ls` then confirms as if it had worked.
Each root now gets a read-only bind mount holding a README that names the tools to
use instead. Read-only as a mount rather than as a mode: the container user has
passwordless sudo, so a chmod would be a suggestion, while `:ro` holds — remounting
needs CAP_SYS_ADMIN. Verified in a scratch container: write, sudo write, sudo chmod,
sudo mount -o remount,rw and sudo rm all fail. And a README rather than an empty
directory, because "Permission denied" is an error, not an instruction — models
answer it by reaching for sudo; the README puts the correction in the same directory
the failing command just named.
The mounts are deliberately not part of `UserFs`: they back no agent path and the
host-side fs-tools must never resolve into them. They reach existing containers as a
fourth self-heal axis in `reusable()`, not as an IMAGE_TAG bump — the image is
unchanged, and a bump would make every installation rebuild it to fix a mount.
The matching half is in `classify_memory`, which now strips the home spellings
(`./`, `~/`, `/root/`) before matching the root. Without it `~/user-memory/x.md`
missed the match and fell through to the disk router — becoming exactly the
invisible physical file the signpost exists to prevent.
`agents/common/memory.md` says the rule outright: the stores are reachable only
through the file tools and `memory_search`, never through `execute_cmd`.
The per-user container shipped python+node and little else, so an agent asking
for `unzip`, `ffprobe` or even `ps` found nothing and had to `sudo apt-get
install` mid-task. That fallback works, but it re-runs on **every container
recreate**, inside the task, where it costs latency and can fail — while the
image is **one, shared by every container**, so preinstalling costs its size
once for the whole box. Anything an agent reaches for repeatedly is therefore
cheaper baked in.
Added on that rule: jq, ripgrep, zip/unzip, xz-utils, sqlite3, wget,
openssh-client, procps, less, file, tzdata, dnsutils, iputils-ping, ffmpeg
(+ffprobe), imagemagick, poppler-utils and tesseract — with the ita/fra
language packs, matching the app's supported UI locales (eng and osd arrive as
hard deps). Deliberately left out: build-essential/python3-dev (~270 MB, only
for a pip package with no wheel) and pandoc (~216 MB) are big *and*
self-recoverable, so they stay on demand. 687 MB -> 1.3 GB, ffmpeg being most
of it.
The image tag goes v2 -> v3, which alone would have equipped nobody: a
container pins the image it was created from, so `ensure()` would have rebuilt
v3 and then happily reused every existing v2 container — the new tools would
have reached only users created from here on. `reusable()` now compares
`.Config.Image` too, turning a tag bump into a recreate, safe for the same
reason the `--user`/`--init` self-heal already is: the container holds no
durable state, everything lives in the bind mounts. An unreadable inspect
answers true, so a docker hiccup never churns a working container.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- Strip ~55 stale upstream docs (dev docs never meant for the agents)
- Write new slim index.md as an agent-facing guide to the app's features
- Add new plugin docs: comfyui, elevenlabs, kokoro_tts, orpheus_tts_3b,
remote_connectivity, whisper_local (replacing old names)
- Add docs_host to UserFs: docs/… and ~/docs/… resolve to {WD}/docs,
mounted read-only at /root/docs in every user's container
- Instruct assistant/kid/project-coordinator agents to read docs/index.md
when users ask how the software works
Rework projects from single-user leftovers into shareable endeavours.
- DB: move `projects` from the owner bucket to the registry (system.db,
not encrypted); add `owner_user_id` + `slug` (drop free `path`); new
`project_members(project_id, user_id, can_write)` mirroring
`shared_folder_members`. Drop `project_tickets` entirely. Only user↔agent
conversations stay encrypted (per-user DB) — each member keeps a private
project chat. Registry home dissolves the cross-DB-FK problem.
- Filesystem/container: on disk `{WD}/projects/{owner_userid}/{slug}`,
agent/container path `projects/{owner_username}/{slug}`. Two-segment routing
in UserFs (ProjectMount + host_base_and_tail arm) and a second loop in
build_user_fs; read-only members get a :ro mount. Reuse the shared-folder
remount machinery (refresh_user_shared_folders -> refresh_user_mounts).
- Remove the ticket system: ProjectTicketManager, UserContext.tickets, its
wiring, and the project_tickets references in scheduled_jobs/cron.
- API: repoint handlers to the registry pool + membership scoping. Sharing is
self-service — owner or any write-member may add/remove members and set
read/write; only the owner deletes; the owner cannot be removed. New
POST/DELETE /api/projects/{id}/members[/{user_id}]. Seed `@fs_any allow
projects/*`; build_runtime_run_context sets working_directory to the agent
path and drops the host-path allow_fs_writes.
- Frontend: create form without the free path field, owner/read-write badges;
the detail page becomes header + description + sharing panel + Open chat + a
file-explorer placeholder (the future primary surface). i18n en/it/fr.
Realizes blueprint §6: each user gets a permanent Docker container
(skald-{userid}, our own skald-runtime image with python+node) as their
execution sandbox. Docker is now a hard requirement — a missing daemon fails
Skald::new and the process exits at boot.
- ContainerManager (crates/skald-core/src/container/): docker availability
check, builds skald-runtime from the embedded Dockerfile, reconciles one
running container per active user at boot, stops them at shutdown, and
ensure/remove on user create/delete. Shells the docker CLI (no client crate).
- UserFs (core-api): pure value type carried in ToolContext, mapping the agent's
single namespace — ~/ → homes/{userid}, shared/{X}/ → shared/{X} (membership),
user-memory/ + shared-memory/ → SQLite — to host and container paths.
- execute_cmd now runs inside the caller's container via `docker exec`.
- fs-tools resolve every physical path through UserFs to the per-user host
workspace, host-side, with fail-closed symlink/`..` containment
(resolve_host_path: canonicalize + prefix-check). grep_files resolves its root
the same way but stays disk-only.
- shared_folders + shared_folder_members (registry, junction table with
can_write) back the shared-folder membership that drives both the container
mounts and the shared/{X} routing.
- Threading: UserContext.fs → ChatSessionManager → handler → ToolContext.fs.
Per-user MCP servers do not yet run in the container (next round).
Daniele
dguiducci