Crate hh_record 

hh-record — the Halfhand recorder layer (SRS §6).

Drives a PTY-recorded agent session: spawns the agent in a PTY (runner), watches the working tree for file changes (watcher), feeds both into the single-writer SQLite store via hh-core, and — when a structured-event adapter applies (FR-1.5, Claude Code today) — drains its parsed events into the same store with tool_call→tool_result correlation. The MCP stdio proxy (FR-2) lives in mcp_proxy.

The threads-vs-tokio decision is recorded in docs/adr/0001-threads-vs-tokio.md.

Structs

GitMeta

Git metadata captured for a session (FR-1.2). All fields are None if the cwd is not a git repo or git is unavailable.

McpProxyOptions

Options for run_mcp_proxy, built by the binary from McpProxyArgs.

McpProxyOutcome

The outcome of a finished proxy run (FR-2).

RunOptions

Per-recording options passed by the binary.

RunOutcome

The outcome of a finished recording (FR-1.6).

Store

The on-disk store: SQLite DB + blob store.

WatchOptions

Options for the filesystem watcher (FR-1.4).

WatcherHandle

A handle to the running watcher thread.

Enums

RecordError

A specialization of hh_core::Error for recorder-originated failures, keeping the cause chain readable for the binary’s anyhow context.

Functions

detect_agent

Detect the agent kind from the command argv (FR-1.2).

run

Run one recording session (FR-1.1, FR-1.3). Creates the session row, spawns the PTY + watcher, drives capture, and finalizes. Returns the outcome for the epilogue (FR-1.6).

run_mcp_proxy

Run the MCP stdio proxy (FR-2). See the module docs for the session model and the forwarding/recording contract.

spawn_watcher

Spawn the watcher thread. Returns Ok(Some(handle)) on success and Ok(None) when filesystem watching could not be set up at all — the matcher could not be built, the notify watcher could not initialize, or even the cwd itself is unwatchable. In every one of those cases the recorder does not abort: it prints a single actionable stderr warning and continues without file-change recording (FR-1.5 best-effort: PTY + adapter capture proceed regardless). Only a failure to spawn the worker thread returns Err (a fatal OS-resource error).

watcher_smoke_test

Self-contained filesystem-watcher smoke test for hh doctor: create a temporary directory, watch it, write a file inside it, and confirm the watcher delivers at least one event within a short deadline. Returns Ok(()) if an event arrived and Err(message) otherwise (notify init failed, the watch could not be added, the watcher reported an error, or no event arrived in time). This exercises the same notify backend the recorder uses, so a failure here explains why a session recorded 0 file changes despite files changing. Read-only with respect to the user’s data dir — it writes only under a throwaway temp directory it cleans up itself.

Type Aliases

Result

A Result alias for the recorder.