Files
craft-ai-integrations/docs/LAYOUT.md
T
JeremyandFredApps be236d570b feat(ai-client): keep a run record as evidence of a real run (#177)
* feat(ai-client): keep a run record as evidence of a real run

AI-17, first slice. `RunRecord` turns a finished job and its plan into one
JSON line: app, tool, capability, provider, connection, model, destination,
the kinds and sizes sent (as the consent screen shows them), parameter names,
start time and duration, outcome, error kind and wording, notices, usage, and
each result's type, size and SHA-256. It keeps no prompt, no result bytes and
no link, since a hosted link can carry a signed token. `to_json_line` refuses
a line that contains any secret it is given, so a key that slipped into an
error message never reaches the file.

The `live_openai` example takes `--record <file>` and appends the line for
its run. No live run was made: tests use a scripted localhost server and the
mock provider. Deliberate-bug group `rr` (10 cases) catches all 10.

* docs(ai-client): say a timed-out wait leaves no run record

Job::wait returns an error on a timeout, so RunOutcome::Unfinished only
comes from a Finished the caller built from a job that had not ended.
Reword the variant's doc and the test that covers it.

* fix(ai-client): clean run-record messages and catch escaped keys

Error and notice text is cleaned when the record is built: the secrets
given to RunRecord::new, the request's own text inputs and any word that
looks like an address are replaced. The record never holds a key, so
serialising it by any route is safe. to_json_line also refuses a line
holding a secret in its JSON-escaped form, so a key with a quote or a
backslash cannot slip past the check.

* fix(ai-client): remove a key inside the request text with the whole text

scrub replaced secrets before it looked for the request text, so a key
inside the prompt broke the prompt's match and left the words around it in
the record. Secrets and request texts are now all found in the original
message and overlapping matches are removed together. The module doc no
longer claims that serialising a record by any route is safe: only its
messages are cleaned, so records are written with to_json_line.

* fix(ai-client): remove overlapping repeats of the request text

match_indices skips overlapping occurrences of the same text, so request
text such as "private private" inside "private private private" left part
of itself behind. Every occurrence is now found, overlapping ones included,
and the spans merge as before.

* fix(ai-client): leak-check the run record and saved image in live_openai

The final leak check only read folders, so the --record file and the
image written by 'image <out.png>' were never read back. It now reads
single files as well as folders, and both are added to the list.

* fix(ai-client): clean parameter text and escaped forms from run records

Error and notice text is now also cleaned of the request's text
parameter values, nested ones included, and of every key and text in
its JSON-escaped form. live_openai refuses a record path that is also
the image output, and its leak check fails when a written file cannot
be read instead of reporting clean. Group rr gains four cases; 24 of
24 caught.

* fix(ai-client): find links in the original text of a run-record message

Links were removed after keys and request text, so request text inside
a link split the address and kept the rest of it, signed token
included. Link spans are now found in the original text and merged with
the others; a merged stretch is named key, then link, then request
text. Also collapses the nested if Clippy flagged in live_openai.
Group rr: 24 of 24 caught.

* docs(ai-client): keep two recorded live runs as evidence

live_openai gains an omni mode (one nano_banana image from a fixed
prompt through the saved ArtCraft Omni connection) and --connection to
pick one saved connection by id. Omni has no free key test, so its
saved model list is used as it stands.

docs/evidence/live-runs.jsonl keeps two records from 11/11/2026: an
OpenAI text run refused with 429 (no API credit) and an Omni image run
that succeeded with one image/png link. STATUS.md says what each shows
and what it does not.

* fix(ai-client): clean returned text and escaped links from run records

Error and notice text is now also cleaned of what the run returned (each
text result and the whole streamed text), read as [result text removed],
and of links written with JSON-escaped slashes. The live_openai docs no
longer promise a hash for a returned link. Group rr: 27 of 27 caught.

* fix(ai-client): protect the shared store from live example outputs

* fix(ai-client): keep record lines whole and resolve parent folders in live_openai

A record appended to a file that ends without a newline now gets one
first, so two records never share a line; append_line moves to its own
module with tests. The output preflight compares names with each parent
folder resolved, so a linked folder or '..' cannot hide that the record
and the image are one file.

* fix(ai-client): keep only the adapter's own words of a run record's messages

Two ways a record could still hold what the person sent or received:
adapters cut long upstream messages at 300 or 360 characters, so a prompt
echoed back arrived cut part-way and never matched whole; and a failed
Gemini image run put the model's own text reply in its error, which was
never an output and so never removed.

Error and notice text now keeps only the adapter's lead. What follows the
first ": " is where adapters quote the service or model, so it becomes
"[detail removed]", and an error records its length and hash. Before the
cut, any stretch of 16 or more characters taken from a request or returned
text is removed too. The record version goes to 2, since `message` changed
meaning and `detail` is new.

The example's record file is now written with one write per line, so two
runs appending at once cannot split a record.

* fix(ai-client): recheck image aliases after recording runs

* test(ai-client): keep the locked-output check true on every Windows machine

Whether a file held with no sharing still has a readable identity differs
between Windows installs: it does on some, and the CI runners refuse it. The
test asserted one outcome, so it passed locally and failed in CI. It now
checks the invariant that holds either way: an unreadable identity is refused
up front, a readable one fails at the write, and the locked file and the
shared store are never changed.

---------

Co-authored-by: FredApps <FredApps@users.noreply.github.com>
2026-11-13 22:01:40 +01:00

5.5 KiB

Layout: what lives where

This repository is the runtime half of the shared AI layer for the Craft apps: one connection, set up once, used by every app that has the tool. It owns connections, models, the tool to model binding, the picker data, consent and jobs. It does not own any app's interface. Each app decides how a tool looks (a prompt bar, a one-click button, a click on the image), in its own repository.

In this repository

Group Crates Owns
Core ai-core, ai-native, ai-client, ai-features The data model and provider trait (wasm-safe), secret stores, the shared store and its location, history and consent files, the app-facing client and tool desk, the tool catalogue and setup options.
Adapters ai-openai, ai-bfl, ai-vertex, ai-artcraft, ai-seedance, ai-comfyui, ai-sam3 One crate per provider API shape. Each is registered in ai-client's ProviderFactory.
HTTP ai-http The one TLS setting every adapter and downloader uses (the platform's certificate check), and a test that fails if any crate builds an agent without it.
Engines ai-engine, ai-engine-candle, ai-engine-rten, ai-engine-burn, ai-burn-setup Models run on this computer: the runner contract, registry and shared provider (ai-engine), and one crate per engine that registers its models (ai-engine-candle, ai-engine-rten and ai-engine-burn, behind ai-client's candle, rten and burn features). ai-burn-setup prepares the saved weights Burn reads, once on this computer. A new model or engine never touches an app.
Local runtime ai-comfy-env, ai-media Finding an existing ComfyUI, model sources and checksummed downloads, node packs, and durable media transfer.
Widgets ai-egui Theme-neutral egui 0.37 widgets (status, consent, progress, connection panel, history, model picker) for apps that have no chrome of their own. See the consumer recipe below.
External interfaces ai-agents The switch that lets AI agents use the Craft apps: the launcher's app list, read and written in one place for the launcher, the gateway and every app.
External interfaces ai-mcp The MCP gateway to the Craft apps: one stdio MCP server that starts each installed app's <app>-cli mcp on demand and offers four tools to find and run their tools. No AI layer dependencies.

Crates keep the flat crates/ folder on purpose. The exact planning checkouts reproduced no app dependency on craft-ai-egui; recheck any current path consumer before moving a crate.

docs/design/ holds design notes. docs/adr/ records each decision that shapes the layer and why, one file each. docs/STATUS.md says what is tested and what is open. docs/evidence/ keeps the run records of real runs. The deliberate-bug scripts are in tools/mutation/; everything a script saves goes through tools/mutation/scrub.py.

Not in this repository

What Where it goes
PhotoCraft's Select subject panel, Generate bar, ai_cmds, hover session storytold/photocraft, through its own PR and its maintainers
The launcher's Set up AI window, History page and ports storytold/craft-launcher
LightCraft's, EffectCraft's and any other app's adapter That app's repository
Anything that draws a toolbar or prompt bar The app. The shared crates never do.

The shared code knows an app only as an AppId string and as data in the catalogue's uses list. If a change here needs to name an app's behaviour, it belongs in the app.

How an app uses this

  1. Declare a role with the tool's id (the catalogue's Feature::role()), for example select-subject. Do not invent an id of your own.
  2. Call AiClient::status to grey the tool out, or to say that a model is needed. Never report a tool with no model as broken.
  3. Depend on a pinned git revision (a tag on main), not a path. Path dependencies are for local work only and must go before an app PR.
  4. A person's choice made for the whole suite is ToolDesk::choose (the default every app reads). AiClient::bind is that one app's own override.

Using the shared egui widgets

craft-ai-egui is optional and has no app adopter in this repository. An egui app repeats the complete [patch.crates-io] recipe in its own root; this repository's patch is not inherited. The reviewed graph is storytold/egui at 6d518fc799681571963842f95b55a6b68431b15a and storytold/winit at a517b3846ee8457d84ee4975110bfda6797c44dc. Keep the library at default-features = false for fonts and let the app choose its font provider (or eframe's bundled fonts). Do not combine this workspace's craft-ai-core with the separate copy in craft-libs; the consumer smoke shows the one-identity check and passes its locked check and one draw test. That headless result is not native GUI acceptance.

Branches

  • main is a state that builds and passes its tests. Apps pin tags on it.
  • Work happens on short-lived branches off main and returns by pull request. A merged branch is deleted, local and remote.
  • Review that matters happens at the boundaries: the shared contract in craft-libs, and each app in its own repository.

Rules that apply to every change

Test first. A deliberate-bug check for safety rules, with no survivor ignored. Cargo targeted with -p, one process at a time, -j 8; no workspace-wide builds. Files under 500 lines. Nothing runs against a real provider, download or ComfyUI without an explicit go. Say plainly what was run and what was not.