mirror of
https://github.com/storytold/photocraft.git
synced 2026-11-13 09:21:55 +00:00
Ahmed Hosny
3e3e580217
* MCP bridge: reconnect before idle sockets die, retry reads, actionable timeouts (#2487) The app closes idle control connections after 30s (IO_TIMEOUT) while the bridge kept one persistent connection, so the first call after a pause failed with "operation may have completed". The bridge now drops and reconnects before sending once the connection has been idle 25s, so a request is never written to a socket the app may have dropped. The default call timeout drops from 60s to 55s, strictly below the app's 60s reply deadline, so the bridge's own error — naming the method and the likely causes — is the one callers see instead of a race between the app's deadline reply and the caller's own cutoff. Idempotent read methods (ui.inspect and friends) get one automatic retry on a transport failure; edits keep #1007 semantics and are never resent. A timed-out call is never retried (it would only double the wait). * MCP bridge: caller-vouched read retries, per-failure wording, docs contract (#2487 review) The retry decision moves from a hand-maintained method list — most of whose entries were engine command ids that never travel as control-protocol methods, so they could never match — to the call sites that know a call is a read: call never resends (#1007), call_read retries once on a transport failure, and the MCP server opts its pure-read tools in. Failures are worded by what they prove: a connection that could never be established is "the request was not sent", not "may have completed"; a read timeout says a read may be retried safely instead of demanding a state inspection. The 55s client cap, the read-retry exception, and the idle reconnect are now documented in the control protocol and the security book.
PhotoCraft Documentation
PhotoCraft is a native image editor written in Rust. This book is the maintained entry point for installation, architecture, formats, automation, development, and security documentation.
The repository's existing docs/ directory remains authoritative for detailed design notes, parity reports, UI conventions, release procedures, and the complete control-protocol method reference. The book links to those documents instead of copying them.
Start here
- Users and evaluators: Installation
- Contributors: Building and Contributing
- Architecture work: Architecture overview
- Agents and automation clients: Automation overview
- Security-sensitive work: Security overview and Threat model
Documentation for coding agents
Coding agents should read the following in order:
AGENTS.mdfor repository rules and verification gates.README.mdfor product scope and current entry points.book/src/architecture/for crate boundaries and command flow.book/src/automation/before driving the CLI, control protocol, or MCP server.book/src/security/before changing a parser, file I/O, automation, MCP, the control server, command execution, or serialization/deserialization.
Agents must treat document bytes, paths, command parameters, and automation messages as untrusted input. A page that describes a proposed control does not mean that control is implemented.
Status language
Security pages use four labels consistently:
- Implemented: behavior confirmed in current source or tests.
- Known limitation: an exposed risk or missing control in current source.
- Proposed: a design direction that is not enforced by the current build.
- Future hardening: useful follow-up work without an accepted implementation yet.