fix(image-generate): save generated images into the caller's workspace
Nightly Build / build (push) Successful in 5m42s

image_generate wrote the file into the server's own data/images/ and handed
that host path to the model. It is a path in nobody's vocabulary: not the
caller's home, not their container. Telegram's send_attachment therefore
resolved it under the user's home and answered "file not found", and
read_file, execute_cmd and the viewer could not reach it either. The web URL
was the only surface that worked, which is why the failure only ever showed
on Telegram -- and why the model there, having no working way to hand the
file over, started inventing send_photo and send_media.

Placement moves to the tool, the one place holding a ToolContext:

- The manager returns bytes (generate_bytes) and no longer knows where an
  image goes. It has no UserFs and no session, so it never could have.

- run_with saves through uploads::save_to_home into uploads/{session}/. The
  returned path is agent vocabulary, so every consumer resolves it, and that
  is the one directory the media inliner is authorized to read from -- a
  vision model can be shown the image it just made. execute_async, the
  context-free path, now fails loudly rather than writing somewhere nobody
  can read; same shape as execute_cmd.

- The extension is sniffed rather than assumed png: it is what decides
  whether Telegram sends the picture inline or as an anonymous document, and
  providers return jpeg and webp too. The file is named after the prompt, so
  it reads as something in the explorer and in Telegram.

The result still carries a url, since the chat renders Markdown images and
![](url) beats naming a file the user then has to open. It points at
/api/file?path=..., which resolves through the caller's own UserFs. The old
/api/images/{id} route is removed: it had no writer left once placement
moved, and it addressed one instance-wide directory behind require_auth
alone, with no notion of who owned the image -- the same shape as the /data
static mount removed before it. That leaves data_root unused, so the manager
no longer knows about the server's filesystem at all.

Docs: the Telegram page explains send_attachment as the channel's equivalent
of show_file_to_user; the ComfyUI page says where a generated image lands and
which of the two handles to use where.

Also introduces CHANGELOG.md and the standing rule for it in CLAUDE.md.
This commit is contained in:
Daniele
2026-08-19 10:29:14 +01:00
parent 66d83358d9
commit 0042f3dbcb
9 changed files with 248 additions and 78 deletions
+8
View File
@@ -444,6 +444,14 @@ Create `agents/<id>/meta.json` and `agents/<id>/AGENT.md`. The agent is discover
`docs/` is **not developer documentation** — it's written for the in-app LLM, not for a human reading the repo, and is mounted read-only into every user's container at `~/docs/` (see the Filesystem & containers section: `docs_host` on `UserFs`, `DOCS_DIR` in `container/mod.rs`). It explains the software's UX (plugins, and eventually agents/connectors/memory/roles/…) in plain terms, in English, so the assistant can help a non-technical user configure things instead of guessing. `docs/index.md` is the entry point (general index of feature pages); `docs/plugins/<plugin id>.md` covers each built-in plugin. The three `type: chat` agents (`assistant`, `kid`, `project-coordinator`) are told in their `AGENT.md` to read `docs/index.md` when a user asks how the software works. **Standing rule: every change that impacts the UX must update `docs/` in the same change** — a new/renamed feature page plus the `docs/index.md` index entry. It goes stale like any other doc, except users actually see this one.
### The changelog
`CHANGELOG.md` (repo root) is the release history, and it carries the **twin standing rule**: every change a user or an operator would notice must add a bullet under `## [Unreleased]` **in the same change** — a feature, a behaviour change, a bug fix, a new config key, an image-tag bump. Same reason as `docs/`: written after the fact it is written from the diff, which is exactly the version nobody can use.
Format is [Keep a Changelog](https://keepachangelog.com): newest first, one `## [x.y.z] - YYYY-MM-DD` section per released version, bullets grouped under `Added` / `Changed` / `Fixed` / `Removed` / `Security`. The versions are the **workspace `Cargo.toml` version** — the same string `ci/verify-version.sh` gates a release PR on — so cutting a release is two edits in one commit: bump `version` in `Cargo.toml`, and rename `## [Unreleased]` to the version with today's date, leaving a fresh empty `Unreleased` above it. There are no git tags on this repo; the changelog *is* the record of what a given `v{version}` tarball contains.
Entries are written **for the person reading the release, not for the person who wrote the code**: say what changed for them, not which module moved — the commit message and the diff already hold that. Which is also the test for whether a bullet is owed at all: a refactor with no observable effect gets none, however large. Keep one bullet per user-visible thing, not one per commit, and fold a fix-on-top-of-an-unreleased-feature into that feature's bullet rather than listing a bug that never shipped. History before `0.2.0` is not covered — git is the record for it.
## Config
Copy `default.config.yaml``config.yml`. Never commit `config.yml` (contains API keys).