A Session with listen = true (the default) now listens on 127.0.0.1 with
the ALPN crafter-debug/1 and writes its discovery record (port, token,
protocol, source id, client path), which goes first when it ends. One
request per stream the client opens: the request and a FIN in, zero or
more stream lines and then the reply and a FIN out, one JSON object per
line.
It holds no thread while nothing arrives. Crafter.Network delivers a
new stream on the pool, its bytes on msquic's worker through OnRecieve,
and replies leave through SendAsync, which never waits. The handler,
which takes the session's mutex, runs on a pool task rather than inside
the stream's callback, so no msquic worker ever waits on the session,
and the session's threads only send, which Network allows under any
lock. Stream wrappers are let go outside every lock their callbacks
take. The rules head the implementation.
Limits: a request over 1 MiB is answered with an error, not buffered,
and a log follower more than 8 MiB behind is reset. quit --force exits
200 ms after its reply was taken, from a thread of its own, since
"sent" means msquic has the bytes, not that they left. A client killed
without closing is let go at the 10 s idle timeout.
The Session refuses a pool without a worker: Network hands it new
streams there, and with Start(1) nothing would run them. The partition
exports nothing, so an app's view of the module is unchanged and it
does not see Crafter.Network's types.
Crafter.Network comes from forgejo, unpinned, with the args unchanged;
--local takes ../Crafter.Network, and $CRAFTER_DEBUG_NETWORK any
project.cpp, for the branch the callback API is on until it lands.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Quit raised the flag and then replied. A main loop that saw the flag in
between could end the Session, and with it the connections, before the
reply was given, and the agent then saw the app vanish (exit 3) instead
of its quit succeed. The reply now goes first: the transport delivers a
reply given before its connections close. quit --force raises the flag
first as before; it exits from the reply's own thread.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
debug.log handed `last` to the timeline query, where 0 means every
entry, so `log --follow --last 0` streamed the whole ring of up to 8192
entries before the new ones, where an agent reads it as tail -n 0 -f:
nothing old, only what comes next. 0 now means no backlog, followed or
not, and the guide says that --follow starts with the last 50.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Session::State has module linkage, and six of its members take Job or
Waiter, which lived in an anonymous namespace: clang warned on each
build that a TU-local entity was exposed (-WTU-local-entity-exposure).
They move to a named namespace, SessionImpl, which this file alone uses
and nothing exports. No behaviour changes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Cli::Run is the whole client but its transport, so tests run it in
process against a real Session; main will hand it the QUIC connection.
- Commands: ls, status, cmds, help, call, get, set, pause, resume,
step, wait, trace, log (with --follow), screenshot, quit, debugger,
guide and version, with -i, --json and --timeout.
- call types key=value from the command's argument schema (slot=1 is
a number, name=1 a string, at.x=3 nests), so agents need no JSON
for simple calls; a value that cannot fit its field is a usage
error before anything is sent.
- The instance comes from discovery; one running instance needs no -i.
The record's protocol is checked before any request: a mismatch
exits 4, says which side is newer and prints the app's own client.
Other sources only warn.
- A request with no reply is diagnosed: the app has exited, stopped
in a debugger (with the attach command), or no longer calls Pump
(with what to change). Exit codes: 2 usage, 3 no instance,
4 version, 5 timeout, 6 the app's error.
- Output is short by default, arrays cut at 20 with a note; --json
prints everything. `guide` is the full reference for agents.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each app writes $HOME/.cache/crafter-debug/instances/<id>.json (0600,
in a 0700 directory) and holds an flock on <id>.lock while it lives.
Every `flatpak run` is its own pid namespace, so pids collide and can
neither name an instance nor tell whether it lives; a random id names
it and the lock says it lives, since flock works across sandboxes on
the shared filesystem. An app killed without its destructor leaves its
files with the lock free, and the next listing removes them. The lock
is created under a temporary name, locked, then renamed, as in
Crafter.Review's LifetimeLock, so it is never seen unlocked while its
app lives. Inside a Flatpak the record also carries the sandbox's
instance id (for `flatpak enter`) and the host pid of its init (to end
the whole sandbox from the host).
project.cpp now generates :BuildInfo per core variant: a hash of the
library's sources and the path of the client built with it. App and
client share the core, so they report the same id exactly when built
from the same sources; this is the safety net under building the
client in the same pass as the app.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The app's end of the connection, independent of the transport, which
reaches it through Detail::Exchange: one request's way back, safe from
any thread and never blocking.
- What needs only the session's own state (hello, status, list, log,
pause, resume) is answered on the transport thread. What touches the
app (calls, get, set, trace, screenshot) queues for the next Pump and
runs on the app's thread between frames. Waits and steps reply from
the Pump that sees them satisfied, events from the thread that emits
them. No request ever holds a thread while it waits.
- A request whose timeout passes before Pump is answered Timeout and
is guaranteed not to have run, so an agent never wonders whether a
command went through; an Async result arrives on the Pump it is
ready; requests left when the Session ends are answered ShuttingDown.
- Advance() for frame loops and Paused()/TakeSteps() for fixed-step
loops hold what the app gates on them; pausing an app that gates
nothing is refused instead of silently doing nothing. pause --when
stops the frame its condition holds; pause --on-check stops before
the next Advance in the frame a check fails, optionally raising
SIGTRAP for an attached debugger.
- A wait that times out says what its condition's paths were; a log
follower gets matching entries in order, from the backlog on, and is
dropped when it cannot keep up.
- Request parameters go through Codec, so a mistyped request gets the
same did-you-mean replies a mistyped command does. The session sets
PR_SET_PTRACER_ANY so a debugger the agent starts can attach.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The app side of Crafter.Debug, minus the session:
- Command(name, description, handler): the handler takes nothing or
one argument struct and returns void, a value, Result<T> or
Async<T>. Arguments are decoded before it runs, so a mistyped call
is answered with every mistake and never reaches it; a throwing
handler becomes an Exception error instead of unwinding into the
frame loop. This replaces 3DForts' three-file pattern per verb.
- Watch(path, variable | getter [, setter]) with bounds, help and
read-only, and Sample(path, value) from any thread with a
frame-stamped history. Paths resolve into values ("bodies[1].pos.y")
and set the same way, writing a member writes the whole value back.
Unknown paths and commands get a suggestion.
- Group: registrations under a prefix that end with their owner. Not
movable, so neither is its owner: its watches refer to the owner's
members, and a move would leave them pointing at the old object.
- Log, LogWarn, LogError, Check and Emit on one frame-stamped
timeline, with source locations captured without macros. A check
failing every frame is counted every time but stored sparsely, and
the session's listener hears every failure.
- Condition: what `wait` and `pause --when` evaluate each frame. A
condition that cannot be decided reports why instead of being false,
which would make a wait hang.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Crafter.Debug.Core is what the app side and the crafter-debug client
both need, without the session:
- Value: a JSON value with its own parser and printer, so no consumer
interface sees a JSON library. Integers stay integers and whole
doubles stay doubles; NaN and the infinities, which JSON cannot
spell, are written as strings rather than hidden, because a debugger
must not lose a NaN; invalid UTF-8 is replaced so output always
parses. Objects keep insertion order, the order an agent reads.
- Reflect: aggregate members and names through structured-binding
packs and source_location, taken from Crafter.DB, plus scoped-enum
names by probing a range of values. Self-tested with static_asserts
so a compiler that changes function_name()'s shape fails the build.
- Codec<T>: encode, decode and describe for bool, integers, floating
point, strings, enums, optional, vector, array, string-keyed maps,
Value, Required<T> and every aggregate. Decode reports every
problem in a call with its path and, for a typo, the likely intended
name, and never throws: a bad call cannot take an app down, which a
wrongly typed parameter could in 3DForts' hand-written from_json.
- Result, Error and Async: handler results, including ones that take
frames to arrive, so callers need no ready:false polling.
project.cpp now builds Crafter.Debug.Core as its own library, used by
both the app library and the client.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A consumer loads Crafter.Debug.Build through
#pragma crafter dependency "<Crafter.Debug>" project "tooling/project.cpp"
and calls Debug::Use in its own CrafterBuildProject, the way
Crafter.LintRules gets in. With the consumer's flag on, Use adds the
library from the checkout the pragma loaded, and writes
build/crafter-debug: a POSIX sh launcher for the client that library
builds. The client is one of the library's dependencies, so a debug
build compiles it in the same pass as the app, from the same sources.
Why a launcher and not a script: every `crafter-build run` loads the
whole project first, which costs 13-28 s per call on 3DForts (a git
pull per unpinned dependency plus rescanning sources), while the
launcher is one sandbox start, 0.08 s. A client built in the Flatpak
links the Flatpak's libc++ against the runtime's glibc, so the launcher
starts it through `flatpak run` and never on the host itself; inside a
CrafterBuild sandbox it runs it directly.
The library, the client and examples/Basic are placeholders that prove
the wiring: the debug build writes a launcher whose client exists, a
plain build has no Crafter::Debug symbols and keeps the notes from
tooling/AGENTS.consumer.md, and a fresh plain build writes a stub that
names the flag.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
