Transactional Agent Runtime

Keep agent changes out of your source checkout until they are verified and safe to apply.

中文详细指南 · Security policy · Contributing · Changelog

Coding agents normally edit the same checkout a developer is using. A failed run, stale test result, concurrent edit, or interrupted process can therefore leave the source in an ambiguous state. Transactional Agent Runtime gives an agent an isolated Git worktree and treats its patch as a prepare/commit transaction.

The source checkout is not updated until the runtime has verified one exact workspace state, authenticated the prepared evidence, and rechecked the source for conflicts at commit time. LangGraph is an included loop adapter, not the transaction core.

See the transaction

No API key or existing repository is required:

python -m pip install mini-code-agent-langgraph
mca tx demo

The demo runs two deterministic transactions. The first proves that a verified patch does not touch the source before commit. The second injects a concurrent source edit and proves that commit is refused without overwriting it. Output is line-oriented and machine-readable on Linux, macOS, and Windows.

Core guarantees

• Clean prepare: agent tools and checks run in an isolated Git worktree; the source remains unchanged before commit.
• Verification binding: passing checks are bound to the exact prepared workspace fingerprint. A later change invalidates them.
• Tamper evidence: a local HMAC-authenticated receipt binds the baseline, patch, verification, trajectory, access log, and prepared fingerprint.
• Conflict refusal: commit rejects a changed source HEAD, any changed source-workspace fingerprint, a changed prepared workspace, or a mismatched patch.

Deliberate limits

• Transactions require a clean Git worktree, and private runtime state must live outside the source repository.
• Conflict detection is intentionally whole-workspace: even an unrelated concurrent source edit rejects commit rather than attempting a merge.
• Receipts are local tamper evidence, not portable signatures, proof of test completeness, or proof that a patch is correct.
• Native Windows has no built-in isolation backend. --sandbox auto requires Docker; --sandbox none is an explicit unisolated opt-out.
• The short pre-apply check is not a filesystem-wide lock against every possible external race.

Run a real transaction

mca tx run "Fix the failing tests" \
  --cwd /path/to/clean/git/repo \
  --model deepseek \
  --check tests "pytest -q"

mca tx status TRANSACTION_ID
mca tx receipt TRANSACTION_ID
mca tx commit TRANSACTION_ID

See the transaction protocol for lifecycle, receipt fields, recovery, and failure behavior. Agent-loop, provider, doctor, and sandbox operations are secondary integrations documented in runtime operations and sandboxing.

Run and chat

The package still includes one-shot mca run, persistent mca chat, DeepSeek and OpenAI-compatible providers, trace inspection, and conflict-aware undo. These are integrations around the transaction core rather than the primary product identity.

See runtime operations for provider setup, verification matrices, chat modes, trajectory handling, and the legacy deterministic demo.

Enforced controls and limits

• New runs and chats reject dirty Git worktrees by default; arbitrary shell access is disabled by default.
• Structured file operations are confined to the resolved workspace, and /ask has a runtime read-only allowlist.
• User-configured authoritative verification—legacy --test-command or named --check entries—must pass against the current workspace fingerprint before submission. A recognized zero-test result is rejected by default, and resume invalidates earlier verification.
• Undo uses a private, HMAC-authenticated journal and rejects post-edit conflicts unless explicitly forced.
• --allow-zero-tests explicitly weakens verification by allowing a recognized zero-test result to satisfy the gate. --sandbox none, --allow-shell, --allow-dirty, --yes, and force/legacy Undo options also deliberately weaken protections; --sandbox auto fails closed if no usable backend is found.
• Native Windows supports transactions and structured tools. Local commands use cmd.exe; process isolation requires Docker.

Read sandboxing for backend boundaries and probes, and the complete security policy for the threat model.

Offline verified-patch benchmark

From a source checkout, reproduce the deterministic v0.3.2 baseline with:

.venv/bin/python -m evals.run_evals --json

The eleven cases cover single-file-fix, multi-file-fix, explain-only, failed-fix-recovery, premature-submission, stale-verification, failed-test-refusal, zero-test-refusal, shell-disabled, checkpoint-resume, and authenticated-undo. The v0.3.2 baseline is 11/11 passing: nine verified submissions, two expected policy refusals, zero unexpected submissions, and zero unrelated changes.

This is offline runtime-policy conformance evidence produced with scripted local decisions. It does not measure model quality, autonomous repair ability, provider behavior, real-world task success, or SWE-bench performance.

Project structure

src/mini_code_agent/agent.py         LangGraph agent loop
src/mini_code_agent/chat.py          Persistent chat session
src/mini_code_agent/executor.py      Tools, approvals, and sandboxing
src/mini_code_agent/verification.py  Workspace-fingerprint verification gate
src/mini_code_agent/trajectory.py    Trajectory, trace, and undo support
src/mini_code_agent/transaction.py   Framework-independent transaction state machine
src/mini_code_agent/transaction_adapter.py Agent tool-call and access-set adapter
src/mini_code_agent/transaction_cli.py Transaction command orchestration and demo
src/mini_code_agent/receipt.py       Authenticated prepared-patch receipts
src/mini_code_agent/locking.py       POSIX/Windows transaction file locks
src/mini_code_agent/security.py      Path and secret protections
src/mini_code_agent/cli.py           CLI and state/configuration handling
tests/                               Deterministic test suite
evals/                               Offline evaluation baseline

Develop and validate a checkout

Cloning the repository and using an editable install are contributor workflows; follow CONTRIBUTING.md for the source setup. In that activated development environment, run:

pytest -q
python -m pip check
python -m evals.run_evals --json
mca doctor --sandbox none
mca demo

mca doctor --sandbox none is a read-only configuration smoke test and intentionally reports an isolation warning. Native Windows runs both demos in CI; use Docker for isolated command execution or WSL2 when POSIX tooling is required by the target repository. For release expectations, see CHANGELOG.md.