Skip to content

Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.

feat(agent): Phase 0 quick wins + roadmap + image-gen research

mrbizarrobc102b14e39f
diff --git a/agent/project.py b/agent/project.py
index e03ca04..7fbc8d2 100644
--- a/agent/project.py
+++ b/agent/project.py
@@ -80,6 +80,96 @@ def read_notes_excerpt(state_dir: Path,
return tail[cut + 1:].decode("utf-8", errors="replace")
+_RING_SLOTS = 7 # 7-version history → ~1 day on a chatty session
+
+
+def _rotate_ring(p: Path) -> None:
+ """Rotate one slot in the .bak ring buffer before write.
+
+ Slot N becomes N+1 (oldest, slot 6, drops). Then current file copies
+ to slot 0. Lets the user (or the agent's `restore_project_notes`
+ affordance) undo a runaway append. Phase 0 #0.12 from the roadmap —
+ project memory survives across sessions but a misclick or runaway
+ agent can corrupt context. Cheap insurance.
+ """
+ try:
+ if not p.is_file():
+ return
+ # Move existing slots up: 5 → 6, 4 → 5, …, 0 → 1.
+ for i in range(_RING_SLOTS - 1, 0, -1):
+ src = p.with_suffix(p.suffix + f".{i - 1}.bak")
+ dst = p.with_suffix(p.suffix + f".{i}.bak")
+ if src.exists():
+ try:
+ os.replace(str(src), str(dst))
+ except OSError:
+ pass
+ # Copy current file to slot 0.
+ slot0 = p.with_suffix(p.suffix + ".0.bak")
+ try:
+ data = p.read_bytes()
+ slot0.write_bytes(data)
+ try:
+ os.chmod(slot0, 0o600)
+ except OSError:
+ pass
+ except OSError:
+ pass
+ except Exception: # noqa: BLE001 — never block the append
+ pass
+
+
+def list_note_versions(state_dir: Path) -> list[dict]:
+ """Return metadata for the available .bak slots — newest first."""
+ p = notes_path(state_dir)
+ out: list[dict] = []
+ for i in range(_RING_SLOTS):
+ slot = p.with_suffix(p.suffix + f".{i}.bak")
+ if slot.is_file():
+ try:
+ stat = slot.stat()
+ out.append({
+ "slot": i,
+ "path": str(slot),
+ "bytes": stat.st_size,
+ "mtime": stat.st_mtime,
+ })
+ except OSError:
+ pass
+ return out
+
+
+def restore_note_version(state_dir: Path, slot: int) -> bool:
+ """Replace the live notes file with the contents of `slot`.
+
+ The restore is itself undoable on the next append — append_note
+ rotates the current (post-restore) file into slot 0 then.
+
+ Important: read the source bytes BEFORE we rotate, otherwise the
+ rotation overwrites the requested slot with the current file's
+ bytes and we'd "restore" the same thing we were trying to undo.
+ """
+ if slot < 0 or slot >= _RING_SLOTS:
+ return False
+ p = notes_path(state_dir)
+ src = p.with_suffix(p.suffix + f".{slot}.bak")
+ if not src.is_file():
+ return False
+ try:
+ # Snapshot source contents first.
+ data = src.read_bytes()
+ tmp = p.with_suffix(p.suffix + ".restoretmp")
+ tmp.write_bytes(data)
+ os.replace(str(tmp), str(p))
+ try:
+ os.chmod(p, 0o600)
+ except OSError:
+ pass
+ return True
+ except OSError:
+ return False
+
+
def append_note(state_dir: Path, text: str, *,
kind: str = "note", author: str = "agent") -> dict:
"""Append a timestamped entry to the notes file.
@@ -92,7 +182,9 @@ def append_note(state_dir: Path, text: str, *,
the agreed master style is "documentary, kodak portra 400, …"
The header on a fresh file describes what the file is for — written
- once on first append.
+ once on first append. Before each append the previous state is
+ rotated into a 7-slot ring buffer (`.0.bak` … `.6.bak`) so a runaway
+ agent or misclick can be undone.
"""
p = notes_path(state_dir)
state_dir.mkdir(parents=True, exist_ok=True)
@@ -100,6 +192,8 @@ def append_note(state_dir: Path, text: str, *,
text = (text or "").strip()
if not text:
raise ValueError("note text is empty")
+ if not fresh:
+ _rotate_ring(p) # snapshot before mutating
ts = datetime.fromtimestamp(time.time()).strftime("%Y-%m-%d %H:%M")
block = f"\n## {ts} [{kind} · {author}]\n{text}\n"
if fresh:
diff --git a/agent/runtime.py b/agent/runtime.py
index a126e16..5bd30f0 100644
--- a/agent/runtime.py
+++ b/agent/runtime.py
@@ -374,6 +374,47 @@ def _escape(s: str) -> str:
# ---- Tools doc renderer ----------------------------------------------------
+def list_tool_catalog() -> list[dict]:
+ """Structured catalog of every registered tool — for the UI's
+ capabilities sheet (Phase 0 #0.5 from the roadmap). One row per
+ tool with `name`, `summary` (first non-empty line of the docstring),
+ and `body` (rest, trimmed). Stable order matches `render_tools_doc`.
+ """
+ order = [
+ "estimate_shot", "submit_shot", "get_queue_status",
+ "wait_for_shot", "extract_frame", "inspect_clip",
+ "generate_shot_images", "get_selected_anchors", "upload_image",
+ "read_document", "list_loras", "get_master_style",
+ "read_project_notes", "append_project_notes",
+ "write_session_manifest", "finish",
+ ]
+ seen = set()
+ out: list[dict] = []
+ def _row(name: str) -> dict | None:
+ fn = tools.TOOL_HANDLERS.get(name)
+ if fn is None:
+ return None
+ doc = (fn.__doc__ or "").strip()
+ if not doc:
+ return {"name": name, "summary": "", "body": ""}
+ lines = doc.split("\n")
+ summary = lines[0].strip()
+ body = "\n".join(lines[1:]).strip()
+ return {"name": name, "summary": summary, "body": body}
+ for name in order:
+ row = _row(name)
+ if row is not None:
+ out.append(row)
+ seen.add(name)
+ for name in sorted(tools.TOOL_HANDLERS.keys()):
+ if name in seen:
+ continue
+ row = _row(name)
+ if row is not None:
+ out.append(row)
+ return out
+
+
def render_tools_doc() -> str:
"""Format the registered tools' docstrings for the system prompt.
diff --git a/docs/AGENTIC_FLOWS_ROADMAP.md b/docs/AGENTIC_FLOWS_ROADMAP.md
new file mode 100644
index 0000000..37c4f36
--- /dev/null
+++ b/docs/AGENTIC_FLOWS_ROADMAP.md
@@ -0,0 +1,109 @@
+# Phosphene Agentic Flows — Roadmap to Pro-App Caliber
+
+_Generated 2026-05-07 by deep UX audit. 50+ items across 4 phases._
+
+## Executive summary
+
+The Agentic Flows tab today is **technically dense and functionally rich** — a careful operator manual, four engine kinds, a memory-pressure guard, a Stage pane that shows live render progress, anchor-pick collaboration, project memory, multi-take support, reasoning surfacing. The single biggest gap is **legibility of capability**: a first-time user opens the tab, sees three vague conversation starters and an engine pill, and has no idea that the agent can read a PDF script, generate Flux anchors, write a manifest, lock a master style across sessions, or refine an existing clip. Sixteen tools, five engines, three image backends, two operating modes, four quality tiers, four shot modes — none of it is discoverable. The product reads as a chat box, not as a director's workstation.
+
+The single biggest opportunity is to **convert hidden depth into a structured workspace**. Replace the pure-chat metaphor with a three-panel surface where chat is the conversation channel, but the project's *state* — script, characters, master style, shot list, picks, renders, manifest — lives in dedicated, navigable, editable structures around it. Sessions become projects. Every artifact the agent produces is first-class and editable by the user. The agent stops being a chatbot that emits files and becomes a director's seat-of-control. This is the move from "Claude can render videos" to "Phosphene's directing agent."
+
+The recommended order of operations: **Phase 0** lands table-stakes professionalism (real first-message streaming, recovery from common error modes, in-app docs, accessibility floor). **Phase 1** rebuilds discoverability and information architecture (capabilities palette, command palette, structured project memory, smart defaults). **Phase 2** adds the wow features that turn casual users into evangelists (project templates, voice memos, comparison view, auto-recovery, NLE export, smart routing). **Phase 3** is the long tail — collaboration, scheduled queues, macros. Phase 0 is roughly 2 weeks of work; Phase 1 is 4–6 weeks; Phase 2 is 4–6 weeks; Phase 3 ships opportunistically.
+
+## Phase 0 — table stakes (~2 weeks)
+
+| # | Item | Effort | Why |
+|---|---|---|---|
+| 0.1 | SSE chat streaming | L | Demo-killer wait; content visible while it generates is the largest perceived-quality lift |
+| 0.2 | Stop button that actually stops (server-side cancel) | M | Today's × only aborts the client; server keeps spending tokens |
+| 0.3 | Recoverable error cards with one-click remediations | M | Errors as paths forward (Retry / Switch model / Stop engine) |
+| 0.4 | In-app capability tour on first run | M | Three-phase loop, anchor-pick UX, overnight-batch model |
+| 0.5 | `/help` slash command + capabilities sheet | S | Surfaces every tool's docstring as a structured catalog |
+| 0.6 | Keyboard accessibility floor (focus-visible, aria-live, reduced-motion) | M | WCAG AA fail today |
+| 0.7 | Session restore on panel restart | M | Half-rendered batches feel orphaned; resume / discard banner |
+| 0.8 | Default-engine recommendation banner | S | New users run bundled Gemma forever; surface Qwen / Anthropic when appropriate |
+| 0.9 | "What just happened?" turn summary | S | 30-card-deep turns lose context; one-line summary at the bottom |
+| 0.10 | Cost / wall-time predictor before submit | S | Total wall + $ before saying "Confirm batch" |
+| 0.11 | Engine readiness check at session start | S | Surface 401 / unreachable BEFORE user uploads attachments |
+| 0.12 | Atomic project-notes history + undo | S | 7-version ring buffer; restore previous version |
+
+## Phase 1 — high-impact polish (4–6 weeks)
+
+| # | Item | Effort |
+|---|---|---|
+| 1.1 | Command palette (Cmd+P) — sessions / shots / tools / settings | M |
+| 1.2 | Capabilities panel + tool catalog | M |
+| 1.3 | Structured project memory (replace single markdown file) | L |
+| 1.4 | Live anchor preview + thumbnail-while-rendering | M |
+| 1.5 | Smart defaults from history | M |
+| 1.6 | Information architecture — collapse the agent header | S |
+| 1.7 | Inline error cards on tool failures | S |
+| 1.8 | Comparison view — two takes side by side | M |
+| 1.9 | Adaptive engine routing (small for tools, big for prose) | L |
+| 1.10 | Voice input → script paste (Whisper) | M |
+| 1.11 | Project templates (documentary / music video / talking head…) | M |
+| 1.12 | Slash commands in composer (`/queue` `/style` `/picks` `/cost` `/finish`) | S |
+| 1.13 | Sketch mode / dry-run on submit_shot | S |
+| 1.14 | Refine UX — show context inline, not just a chip | S |
+| 1.15 | RAM chip → live system pulse with breakdown popover | S |
+| 1.16 | Discoverability for engine kinds (radio cards w/ pricing) | S |
+| 1.17 | Session export to markdown | S |
+| 1.18 | Project export bundle (zip with manifest + mp4s + picks + transcript) | M |
+| 1.19 | Reasoning indicator with throughput | S |
+| 1.20 | Modal focus traps + escape keys | S |
+| 1.21 | Empty states everywhere have actions | S |
+
+## Phase 2 — delight (4–6 weeks)
+
+| # | Item | Effort |
+|---|---|---|
+| 2.1 | Live thumbnail preview during LTX render | L |
+| 2.2 | Shot timeline view (drag to reorder) | L |
+| 2.3 | NLE export — Final Cut XML / Premiere XML | M |
+| 2.4 | Auto-recovery from engine errors mid-batch | M |
+| 2.5 | Smart-route to Anthropic on Qwen reasoning loop detection | M |
+| 2.6 | Inline annotation on a clip | L |
+| 2.7 | Pre-defined macros (saved prompt sequences) | M |
+| 2.8 | Background mode + scheduled queues | M |
+| 2.9 | LoRA picker the agent can recommend from | S |
+| 2.10 | Acid-test "this prompt won't work" guardrail w/ Director's note | M |
+| 2.11 | Cross-session search | M |
+| 2.12 | Showcase / public gallery (static HTML) | L |
+| 2.13 | Director's chair keyboard shortcuts (J/K/L/P/R) | S |
+| 2.14 | Anchor prompt expansion ("more like this but darker") | S |
+| 2.15 | Dry-run cost estimate per-shot | S |
+
+## Phase 3 — long tail (opportunistic)
+
+| # | Item |
+|---|---|
+| 3.1 | Multi-machine collaboration (iCloud-synced sessions) |
+| 3.2 | Session fork ("try a different direction") |
+| 3.3 | Live URL share for trusted machines |
+| 3.4 | Image-engine: DiffusionKit / CoreML on ANE |
+| 3.5 | Sketched anchor input (canvas painter → ControlNet Flux) |
+| 3.6 | Multi-agent — director + cinematographer split |
+| 3.7 | Real-time render preview in chat |
+| 3.8 | Auto-stitch optional draft cut |
+| 3.9 | Engine A/B comparison mode |
+| 3.10 | Semantic diff between takes |
+| 3.11 | Whisper inline as speech-to-shot (silence-segmented chunking) |
+| 3.12 | OBS / streaming integration |
+| 3.13 | Pull-request-style review of the agent's plan |
+
+## Critical implementation seams
+
+Every roadmap item names a specific file + function or HTML element. Most land in:
+
+- `mlx_ltx_panel.py` (~16,900 lines) — single file with HTTP server + inlined HTML/CSS/JS. Key seams: `#agentChat`, `agentSend()`, `renderEmpty()`, `renderToolResultCard()`, `renderAnchorGrid()`, agent header, Stage pane (`agentStageRender()`), settings drawer, sessions sidebar (`aspInit()`), composer.
+- `agent/runtime.py` — `Session` + `run_turn`. SSE streaming, cancel support, auto-recovery, multi-engine routing.
+- `agent/tools.py` — every tool with docstrings consumed by the system prompt. New tools, `dry_run` flag, `prompt_diff` arg.
+- `agent/prompts.py` — system prompt builder. Project templates inject addenda; structured project memory replaces `{project_notes_block}`.
+- `agent/engine.py` — OpenAI/Anthropic client. SSE deltas, cancel-via-connection-close, reasoning-loop detection emits structured `recommend_engine` error.
+- `agent/project.py` — markdown notes. Add `read_structured()` parsing `[<kind> · ...]` sections; add ring buffer for undo.
+- `agent/image_engine.py` — backends. Refactor to a generator so candidates stream as they finish.
+- `docs/AGENTIC_FLOWS.md` + `docs/STATE.md` — source of truth. Every shipped item gets a row.
+
+## The agent-tool connection rule (from `docs/AGENTIC_FLOWS.md`)
+
+Every new manual UI feature must also be exposed to the agent as a tool. New roadmap features that introduce manual surfaces (timeline view, comparison view, macros, scheduled queues) need matching agent tools.
diff --git a/docs/IMAGE_GEN_RESEARCH_2026-05.md b/docs/IMAGE_GEN_RESEARCH_2026-05.md
new file mode 100644
index 0000000..dd287fa
--- /dev/null
+++ b/docs/IMAGE_GEN_RESEARCH_2026-05.md
@@ -0,0 +1,118 @@
+# Phosphene Image-Gen Research — Apple Silicon, May 2026
+
+_Tier-aware research for the agent's anchor-still pipeline (i2v inputs).
+LTX 2.3's t2v is weak; image-gen quality is the dominant lever for video output._
+
+## TL;DR
+
+- **"Flux Klein"** = **FLUX.2 [klein] 4B** by Black Forest Labs (Jan 2026). Apache 2.0, mflux-compatible at 4-bit (~4.3 GB), 4-step inference, ~12-18 s/image on Comfortable Mac. **Ship as default.**
+- **mflux 0.17.x is now multi-family.** Legacy `mflux-generate` is FLUX.1-only. New CLIs: `mflux-generate-flux2`, `mflux-generate-z-image-turbo`, `mflux-generate-fibo`, `mflux-generate-qwen`, `mflux-generate-kontext`. Panel currently calls legacy → silently misses every new family.
+- **Z-Image-Turbo (Tongyi/Alibaba, Nov 2025)** is the Compact-tier default — 6B model, ~5.9 GB at 4-bit, 8-9 steps, fits 16 GB.
+
+## The single default to ship
+
+**FLUX.2 [klein] 4B at 4-bit, 4 steps** via:
+
+```
+mflux-generate-flux2 \
+ --model Runpod/FLUX.2-klein-4B-mflux-4bit \
+ --base-model flux2-klein-4b \
+ --steps 4 \
+ --quantize 4 \
+ --guidance 1.0
+```
+
+Apache 2.0 → no gating, commercial OK. ~4.3 GB on disk, fits Compact tier with LTX dormant. 4 candidates per shot in 50-75 s on Comfortable. Multi-reference editing built-in.
+
+## Tier-aware defaults
+
+| Tier | RAM | Default model | Quant | Steps | Wall time |
+|---|---|---|---|---|---|
+| Compact | 16-32 GB | `Tongyi-MAI/Z-Image-Turbo` (mflux-4bit) | 4 | 9 | ~15-25 s |
+| Comfortable | 32-79 GB | `Runpod/FLUX.2-klein-4B-mflux-4bit` | 4 | 4 | ~12-18 s |
+| Roomy | 80-119 GB | klein-4B 8-bit OR Krea-dev 8-bit | 4-8 | 4-25 | ~18-80 s |
+| Studio | 120 GB+ | klein-4B 4-bit OR FLUX.2-dev 4-bit | 4 | 4 | ~12 s |
+
+Auto-detect snippet:
+```python
+def _default_image_engine_for_tier(tier: str) -> dict:
+ if tier == "base": # Compact
+ return {"kind": "mflux", "family": "z_image_turbo",
+ "model_path": "filipstrand/Z-Image-Turbo-mflux-4bit",
+ "steps": 9, "quantize": 4, "guidance": 0.0}
+ if tier in ("standard", "high", "pro"):
+ return {"kind": "mflux", "family": "flux2",
+ "model_path": "Runpod/FLUX.2-klein-4B-mflux-4bit",
+ "steps": 4, "quantize": 4, "guidance": 1.0}
+ return {"kind": "mock"}
+```
+
+## Model landscape (mflux-friendly repos)
+
+| Model | Repo | Params | 4-bit GB | License | Steps |
+|---|---|---|---|---|---|
+| **FLUX.2-klein-4B** | `Runpod/FLUX.2-klein-4B-mflux-4bit` | 4B | **4.3** | **Apache 2.0** | **4** |
+| FLUX.2-klein-9B | community ports forming | 9B | ~9-11 | Non-commercial | 4-8 |
+| FLUX.2-dev | `black-forest-labs/FLUX.2-dev` | 32B | ~16-18 | Non-commercial | 25-50 |
+| **Z-Image-Turbo** | **`filipstrand/Z-Image-Turbo-mflux-4bit`** | 6B | **5.9** | **Apache 2.0** | **8-9** |
+| Z-Image (base) | `Tongyi-MAI/Z-Image` | 6B | ~6.5 | Apache 2.0 | 25 |
+| FLUX.1-Krea-dev | `filipstrand/FLUX.1-Krea-dev-mflux-4bit` | 12B | 9.61 | Non-commercial (gated) | 25 |
+| FLUX.1-dev | `madroid/flux.1-dev-mflux-4bit` | 12B | ~9.5 | Non-commercial (gated) | 25-50 |
+| FLUX.1-schnell | `dhairyashil/FLUX.1-schnell-mflux-4bit` | 12B | ~9 | Apache 2.0 | 2-4 |
+| FIBO | `briaai/FIBO` | 8B | ~10-12 | Open-RAIL-ish | 30 |
+| Qwen-Image | `filipstrand/Qwen-Image-mflux-6bit` | 20B | ~16 (6-bit) | Apache 2.0 | 25-50 |
+| Flex.1-alpha | `ostris/Flex.1-alpha` | 8B | ~9-10 | Apache 2.0 | 25 |
+
+## mflux 0.17.x per-family CLIs
+
+| Command | Family |
+|---|---|
+| `mflux-generate` (legacy) | flux1 |
+| `mflux-generate-flux2` | flux2 (klein-4B, klein-9B, dev) |
+| `mflux-generate-flux2-edit` | flux2 image-edit |
+| `mflux-generate-z-image` | z_image base |
+| `mflux-generate-z-image-turbo` | z_image_turbo |
+| `mflux-generate-fibo` | fibo |
+| `mflux-generate-fibo-edit` | fibo edit (incl. remove-bg) |
+| `mflux-generate-qwen` | qwen |
+| `mflux-generate-kontext` | flux1-kontext |
+| `mflux-generate-fill` | flux1 inpaint |
+| `mflux-generate-controlnet` | flux1 controlnet |
+| `mflux-upscale-seedvr2` | seedvr2 upscaler (could replace pipersr!) |
+
+All share the same argparse mixins — `--prompt`, `--negative-prompt`, `--width`, `--height`, `--steps`, `--guidance`, `--seed`, `--quantize`, `--model`, `--base-model`, `--output`, `--metadata`, `--lora-paths`, `--lora-scales`, `--image-path`, `--image-strength`.
+
+## Implementation plan (20 ranked items)
+
+1. **(M)** Family-aware `_resolve_mflux_bin` in `agent/image_engine.py:131` + new `MFLUX_FAMILY_BIN` lookup table. Without this, none of the 0.17 families are reachable.
+2. **(M)** Per-family default-flag table in `_generate_mflux`. klein-4B uses 4 steps + guidance 1; Z-Image-Turbo uses 9 steps + guidance 0; Krea-dev keeps 25 + guidance 4.5.
+3. **(L)** Tier auto-detect via `_default_image_engine_for_tier` in `mlx_ltx_panel.py:~2042`. Apply at first boot when `agent_image_config.json` doesn't exist.
+4. **(M)** Add FLUX.2-klein-4B to the model dropdown — `mlx_ltx_panel.py:10881`. Add `<optgroup>` per family.
+5. **(M)** Add Z-Image-Turbo to the model dropdown.
+6. **(M)** "Quality dial" pill group above the model dropdown — Fast (Z-Image-Turbo) / Balanced (klein-4B 4-bit) / Max (Krea-dev 8-bit on Roomy+, klein-4B 4-bit elsewhere).
+7. **(M)** Reuse `_hf_model_install_async` for image weights — "Download" button in image drawer. Pre-flight via `_hf_size_estimate`.
+8. **(S)** `health_check` extension reporting `weights_downloaded: bool` per family. Surface in Settings drawer pill.
+9. **(M)** "Test current pipeline" button — runs portrait prompt at n=1, shows wall-time inline.
+10. **(M)** OOM pre-flight: `if (model_gb + LTX_peak_gb > tier_ram): refuse + suggest 4-bit`.
+11. **(M)** Tier-aware subprocess timeout — 240s for klein-4B/Z-Image, 600s for Krea-dev/dev.
+12. **(L)** `mflux_warm_helper.py` — long-lived subprocess that loads the model once and accepts prompts via stdin. Mirror `mlx_warm_helper.py`. Saves 25-50s cold-load per shot batch.
+13. **(M)** Sibling venv `image-gen/env/` so mflux deps don't conflict with LTX's transformers/mlx pins. `_resolve_mflux_bin` checks there first.
+14. **(S)** HF gating UX — when `_hf_size_estimate` returns `gated: true`, surface "Open HF model card → accept terms → paste HF_TOKEN" inline.
+15. **(S)** Update `docs/AGENTIC_FLOWS.md § Image generation backends` — document family dispatch, tier defaults, deprecate legacy `mflux-generate`-only path.
+16. **(S)** Update `agent/image_engine.py:1-28` module docstring — current still says "Two backends ship in v1: mock, bfl" with mflux as "future".
+17. **(M)** Tier-aware default for `ImageEngineConfig.mflux_model` (was `"krea-dev"` — wrong for 16 GB Macs).
+18. **(L)** "Compare models" Settings page — runs test prompt across 3 picks side-by-side, click to set as default.
+19. **(L)** Add `mflux-upscale-seedvr2` as post-render option for image candidates.
+20. **(S)** Surface `--metadata` flag (writes JSON sidecar with prompt+seed+steps+model). Save next to candidate PNG.
+
+## Sources
+
+- [filipstrand/mflux on GitHub](https://github.com/filipstrand/mflux)
+- [mflux releases page](https://github.com/filipstrand/mflux/releases)
+- [black-forest-labs/FLUX.2-klein-4B on HF](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B)
+- [Runpod/FLUX.2-klein-4B-mflux-4bit on HF (~4.3 GB)](https://huggingface.co/Runpod/FLUX.2-klein-4B-mflux-4bit)
+- [BFL FLUX.2 [klein] launch blog](https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence)
+- [Tongyi-MAI/Z-Image-Turbo on HF](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)
+- [filipstrand/Z-Image-Turbo-mflux-4bit on HF (~5.9 GB)](https://huggingface.co/filipstrand/Z-Image-Turbo-mflux-4bit)
+- [filipstrand/FLUX.1-Krea-dev-mflux-4bit on HF (9.61 GB)](https://huggingface.co/filipstrand/FLUX.1-Krea-dev-mflux-4bit)
+- [Apatero — Flux on Apple Silicon performance guide](https://www.apatero.com/blog/flux-apple-silicon-m1-m2-m3-m4-complete-performance-guide-2025)
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index 73a7b1b..d45db0a 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -4598,6 +4598,35 @@ class Handler(BaseHTTPRequestHandler):
})
return
+ if parsed.path == "/agent/capabilities":
+ # Structured tool catalog — drives the in-app /help sheet so
+ # users discover what the agent can actually do (Phase 0 #0.5).
+ try:
+ catalog = agent_runtime.list_tool_catalog()
+ except Exception as e: # noqa: BLE001
+ self._json({"error": str(e)}, 500); return
+ self._json({
+ "tools": catalog,
+ "engine_kinds": [
+ {"id": "phosphene_local", "label": "Phosphene Local", "cost": "free · on-device"},
+ {"id": "anthropic", "label": "Claude (Anthropic)", "cost": "paid · per token"},
+ {"id": "ollama", "label": "Ollama bridge", "cost": "free · on-device"},
+ {"id": "custom", "label": "Custom (OpenAI-compat)", "cost": "depends"},
+ ],
+ "image_kinds": [
+ {"id": "mock", "label": "Mock", "cost": "free · placeholders"},
+ {"id": "mflux", "label": "Local Flux (mflux)", "cost": "free · uses RAM + disk"},
+ {"id": "bfl", "label": "Black Forest Labs API", "cost": "paid · per image"},
+ ],
+ "modes": [
+ {"id": "plan_sleep", "label": "Plan & sleep", "desc": "Auto-stop engine on finish; frees RAM for renders"},
+ {"id": "interactive", "label": "Interactive", "desc": "Engine stays resident across finishes"},
+ ],
+ "shot_modes": ["t2v", "i2v", "keyframe", "extend"],
+ "quality_tiers": ["quick", "balanced", "standard", "high"],
+ })
+ return
+
if parsed.path == "/agent/sessions":
self._json({"sessions": agent_runtime.list_sessions(STATE_DIR)})
return
@@ -5815,6 +5844,27 @@ HTML = r"""<!doctype html>
}
* { box-sizing: border-box; }
html, body { margin: 0; height: 100%; }
+
+ /* Phase 0 a11y floor —
+ (a) Visible focus ring on every interactive element when reached
+ via keyboard (mouse-click clears via :focus-visible). Today's
+ inputs had ad-hoc focus styling but buttons/links had none.
+ (b) Honor reduced-motion. Animations / transitions across the app
+ use ms-scale durations; this collapses them to ~zero so motion-
+ sensitive users don't get pulse / slide / fade. */
+ :focus-visible {
+ outline: 2px solid var(--accent-bright);
+ outline-offset: 2px;
+ border-radius: var(--r-xs);
+ }
+ @media (prefers-reduced-motion: reduce) {
+ *, *::before, *::after {
+ animation-duration: 0.01ms !important;
+ animation-iteration-count: 1 !important;
+ transition-duration: 0.01ms !important;
+ scroll-behavior: auto !important;
+ }
+ }
body {
background: var(--bg); color: var(--text);
font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
@@ -8050,6 +8100,99 @@ HTML = r"""<!doctype html>
margin: 14px 0;
}
+ /* ---- Capabilities sheet (Phase 0 #0.5) ----
+ Drives the /help slash-command output. Each tool is one row:
+ monospaced name + first-line summary; click to expand the full
+ docstring. Quiet typography — this is reference material. */
+ .caps-section {
+ margin: 14px 0;
+ }
+ .caps-section h3 {
+ margin: 0 0 8px 0;
+ font-size: 11px;
+ letter-spacing: 0.5px;
+ text-transform: uppercase;
+ color: var(--muted);
+ font-weight: 600;
+ }
+ .caps-row {
+ display: flex;
+ gap: 12px;
+ padding: 10px 12px;
+ border: 1px solid var(--border);
+ border-radius: var(--r-sm);
+ margin-bottom: 6px;
+ background: rgba(255,255,255,0.025);
+ }
+ .caps-row .caps-name {
+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+ font-size: 11.5px;
+ color: var(--accent-bright);
+ white-space: nowrap;
+ flex-shrink: 0;
+ align-self: flex-start;
+ padding-top: 1px;
+ }
+ .caps-row .caps-text {
+ flex: 1; min-width: 0;
+ font-size: 12px;
+ color: var(--text);
+ line-height: 1.5;
+ }
+ .caps-row .caps-text .summary {
+ color: var(--muted);
+ font-size: 11.5px;
+ }
+ .caps-row details {
+ margin-top: 4px;
+ }
+ .caps-row details summary {
+ cursor: pointer;
+ font-size: 11px;
+ color: var(--accent-bright);
+ list-style: none;
+ user-select: none;
+ }
+ .caps-row details summary::-webkit-details-marker { display: none; }
+ .caps-row details[open] summary { color: var(--muted); }
+ .caps-row pre {
+ margin: 6px 0 0 0;
+ padding: 10px 12px;
+ background: var(--bg);
+ border: 1px solid var(--border);
+ border-radius: var(--r-xs);
+ font-size: 11px;
+ line-height: 1.55;
+ max-height: 280px;
+ overflow: auto;
+ white-space: pre-wrap;
+ word-break: break-word;
+ color: rgba(255,255,255,0.8);
+ }
+ .caps-grid {
+ display: grid;
+ grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+ gap: 8px;
+ }
+ .caps-grid .caps-cell {
+ padding: 9px 12px;
+ border: 1px solid var(--border);
+ border-radius: var(--r-sm);
+ background: rgba(255,255,255,0.025);
+ }
+ .caps-grid .caps-cell .label {
+ font-weight: 600; font-size: 12px; color: var(--text);
+ }
+ .caps-grid .caps-cell .meta {
+ color: var(--muted); font-size: 11px;
+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+ letter-spacing: 0.2px;
+ }
+ .caps-grid .caps-cell .desc {
+ color: var(--muted); font-size: 11.5px;
+ margin-top: 2px;
+ }
+
/* ---- Reasoning disclosure (chain-of-thought) ----
Shown above the assistant content as a collapsed details block.
Quiet by default so the answer stays the focus; expanding reveals
@@ -9798,6 +9941,13 @@ HTML = r"""<!doctype html>
<line x1="3" y1="21" x2="10" y2="14"/>
</svg>
</button>
+ <button type="button" class="icon-btn" onclick="openAgentCaps()" title="What can the agent do? · type /help in chat" aria-label="Show agent capabilities">
+ <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+ <circle cx="12" cy="12" r="10"></circle>
+ <path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"></path>
+ <line x1="12" y1="17" x2="12.01" y2="17"></line>
+ </svg>
+ </button>
<button type="button" class="icon-btn" onclick="openProjectNotes()" title="Project notes — persistent memory across sessions">
<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z"/>
@@ -9815,7 +9965,7 @@ HTML = r"""<!doctype html>
</header>
<div class="agent-chat-wrap">
- <div class="agent-chat" id="agentChat"></div>
+ <div class="agent-chat" id="agentChat" role="log" aria-live="polite" aria-relevant="additions" aria-label="Agent chat thread"></div>
<!-- "↓ new messages" pill — appears when content lands while the
user has scrolled up to read something. Clicking jumps to
bottom and re-arms auto-scroll. -->
@@ -9886,7 +10036,7 @@ HTML = r"""<!doctype html>
<polyline points="5 12 12 5 19 12"/>
</svg>
</button>
- <span class="hint">Cmd/Ctrl + Enter to send · ⌘V to paste · drag files to attach</span>
+ <span class="hint">⌘ Enter to send · ⌘V to paste · drag files to attach · type /help to see what the agent can do</span>
</div>
<!-- Drag-drop overlay shown only while a drag is over the chat surface. -->
<div class="agent-drop-overlay" id="agentDropOverlay">
@@ -10723,6 +10873,28 @@ HTML = r"""<!doctype html>
</div>
</div>
+<!-- ============== CAPABILITIES SHEET ==============
+ Triggered by typing /help in the composer or clicking the ? button.
+ Driven by /agent/capabilities (server-side enumeration of all
+ registered tools + engine kinds + image kinds + modes). Lets users
+ discover what the agent can do without grepping the system prompt. -->
+<div class="agent-settings-modal" id="agentCapsModal"
+ role="dialog" aria-modal="true" aria-labelledby="agentCapsTitle"
+ onclick="if(event.target===this)closeAgentCaps()">
+ <div class="agent-settings-card" style="max-width:780px">
+ <h2 id="agentCapsTitle">What the agent can do
+ <button type="button" onclick="closeAgentCaps()">Close</button>
+ </h2>
+ <div class="hint">
+ Phosphene's agent is a director's assistant. It plans shots,
+ generates anchor stills, queues LTX renders, writes a manifest.
+ Below: every tool it has, plus the engine and image-backend
+ options. Use this as a reference; you don't need to memorize it.
+ </div>
+ <div id="agentCapsBody" style="padding-top:8px"></div>
+ </div>
+</div>
+
<!-- ============== PROJECT NOTES MODAL ============== -->
<!-- Persistent memory across sessions — the agent reads the tail of
this file every turn. Editable here too. -->
@@ -15300,6 +15472,18 @@ async function agentSend() {
const btn = document.getElementById('agentSendBtn');
const text = (input.value || '').trim();
+ // Slash commands handled client-side BEFORE engaging the engine.
+ // /help opens the capabilities sheet; /notes opens project notes;
+ // /queue triggers the batch; /clear starts a new session; etc.
+ if (text && text.startsWith('/') &&
+ typeof agentMaybeHandleSlashCommand === 'function' &&
+ agentMaybeHandleSlashCommand(text)) {
+ input.value = '';
+ if (typeof agentAutoResize === 'function') agentAutoResize(input);
+ if (typeof agentUpdateSendState === 'function') agentUpdateSendState();
+ return;
+ }
+
// Wait for any in-flight uploads so the message arrives WITH its
// attachments. UX: don't block the user — if uploads error we surface
// them in the chip row and the user can remove/retry.
@@ -15827,6 +16011,134 @@ function closeAgentSettings() {
}
// ---- Project notes modal --------------------------------------------------
+// Capabilities sheet — driven by /agent/capabilities. Surfaces every
+// tool the agent has, plus engine/image/mode options, so users
+// discover what they can ask for. (Phase 0 #0.5)
+async function openAgentCaps() {
+ const modal = document.getElementById('agentCapsModal');
+ const body = document.getElementById('agentCapsBody');
+ if (!modal || !body) return;
+ body.innerHTML = '<div style="padding:24px; color:var(--muted); text-align:center">Loading…</div>';
+ modal.classList.add('open');
+ try {
+ const r = await fetch('/agent/capabilities');
+ const j = await r.json();
+ body.innerHTML = '';
+ // Tools
+ if (Array.isArray(j.tools) && j.tools.length) {
+ const sec = document.createElement('div');
+ sec.className = 'caps-section';
+ const h = document.createElement('h3');
+ h.textContent = `Tools the agent can call · ${j.tools.length}`;
+ sec.appendChild(h);
+ for (const t of j.tools) {
+ const row = document.createElement('div');
+ row.className = 'caps-row';
+ const name = document.createElement('div');
+ name.className = 'caps-name';
+ name.textContent = t.name;
+ const txt = document.createElement('div');
+ txt.className = 'caps-text';
+ const sum = document.createElement('div');
+ sum.className = 'summary';
+ sum.textContent = t.summary || '(no summary)';
+ txt.appendChild(sum);
+ if (t.body) {
+ const det = document.createElement('details');
+ const dsum = document.createElement('summary');
+ dsum.textContent = 'Show full doc';
+ det.appendChild(dsum);
+ const pre = document.createElement('pre');
+ pre.textContent = t.body;
+ det.appendChild(pre);
+ txt.appendChild(det);
+ }
+ row.appendChild(name); row.appendChild(txt);
+ sec.appendChild(row);
+ }
+ body.appendChild(sec);
+ }
+ // Engine kinds
+ const _gridSection = (title, items, render) => {
+ if (!Array.isArray(items) || !items.length) return;
+ const sec = document.createElement('div');
+ sec.className = 'caps-section';
+ const h = document.createElement('h3'); h.textContent = title;
+ sec.appendChild(h);
+ const grid = document.createElement('div');
+ grid.className = 'caps-grid';
+ for (const it of items) grid.appendChild(render(it));
+ sec.appendChild(grid);
+ body.appendChild(sec);
+ };
+ _gridSection('Chat engine kinds', j.engine_kinds || [], (e) => {
+ const c = document.createElement('div'); c.className = 'caps-cell';
+ c.innerHTML = `<div class="label">${escapeHtml(e.label)}</div>` +
+ `<div class="meta">${escapeHtml(e.id)}</div>` +
+ `<div class="desc">${escapeHtml(e.cost)}</div>`;
+ return c;
+ });
+ _gridSection('Image-engine backends', j.image_kinds || [], (e) => {
+ const c = document.createElement('div'); c.className = 'caps-cell';
+ c.innerHTML = `<div class="label">${escapeHtml(e.label)}</div>` +
+ `<div class="meta">${escapeHtml(e.id)}</div>` +
+ `<div class="desc">${escapeHtml(e.cost)}</div>`;
+ return c;
+ });
+ _gridSection('Operating modes', j.modes || [], (e) => {
+ const c = document.createElement('div'); c.className = 'caps-cell';
+ c.innerHTML = `<div class="label">${escapeHtml(e.label)}</div>` +
+ `<div class="meta">${escapeHtml(e.id)}</div>` +
+ `<div class="desc">${escapeHtml(e.desc)}</div>`;
+ return c;
+ });
+ } catch (e) {
+ body.innerHTML = `<div style="padding:18px;color:#f49a9e">Couldn't load capabilities: ${escapeHtml(String(e))}</div>`;
+ }
+}
+
+function closeAgentCaps() {
+ const m = document.getElementById('agentCapsModal');
+ if (m) m.classList.remove('open');
+}
+
+// Slash-command pre-handler. Called from agentSend BEFORE the send fires.
+// Returns true if the slash command was handled (don't continue with
+// the normal send), false otherwise.
+function agentMaybeHandleSlashCommand(text) {
+ const t = (text || '').trim();
+ if (!t.startsWith('/')) return false;
+ const cmd = t.split(/\s+/)[0].toLowerCase();
+ switch (cmd) {
+ case '/help':
+ case '/?':
+ openAgentCaps();
+ return true;
+ case '/notes':
+ openProjectNotes();
+ return true;
+ case '/queue':
+ case '/picks':
+ // If anchor picks are pending, fire the existing batch flow.
+ if (typeof agentBatchQueue === 'function') {
+ agentBatchQueue();
+ } else {
+ alert('No anchors picked yet — generate some first.');
+ }
+ return true;
+ case '/clear':
+ case '/new':
+ if (typeof agentNewSession === 'function') agentNewSession();
+ return true;
+ case '/settings':
+ case '/engine':
+ if (typeof openAgentSettings === 'function') openAgentSettings();
+ return true;
+ default:
+ return false; // unknown slash — let it through
+ }
+}
+
async function openProjectNotes() {
const modal = document.getElementById('agentNotesModal');
const ta = document.getElementById('agentNotesTextarea');