car_server_core/coder/

mod.rs

//! Built-in coding agent ("CAR Coder").
//!
//! The user states an intent; the coder turns it into a **verifiable outcome
//! contract** (shell commands that must pass), gets it confirmed, then works in
//! a throwaway **git worktree** until every check is green — natively (CAR
//! inference + policy-gated tools) or by delegating to an installed external
//! CLI (Claude Code, Codex, Gemini), with CAR re-running the contract either
//! way. Results are published as a `car/coder/<id>` branch in the user's repo;
//! the user's checkout is never touched.
//!
//! ## Module map
//!
//! - [`contract`] — `OutcomeContract` derivation (inference, repair loop) and
//!   evaluation (runs checks through the policy-gated shell tool)
//! - [`session`] — session state machine, event stream (`CoderEvent`), JSON
//!   snapshots under `~/.car/coder/`
//! - [`shell_tool`] — `WorktreeExecutor`: file tools + a host `shell` tool,
//!   all rooted/clamped at the worktree and gated by the inspector chain
//! - [`policy`] — the coder inspector set (no pushes, no privilege escalation,
//!   no writes outside the worktree, …)
//! - [`native_loop`] — the plan→edit→verify→repair loop driving CAR inference
//! - [`router`] — engine selection between the native loop and external CLIs
//! - [`merge`] — squash-commit the worktree and deliver it: a local branch,
//!   a managed project's `main`, or (headless) an append-only push plus one
//!   reconciled pull request
//! - [`discuss`] — repo-grounded, strictly READ-ONLY conversation that can be
//!   distilled into a run intent (`coder.discuss.*`); it never starts a session
//! - [`fix_issues`] — files a dogfooding round's durable-fix proposals as
//! - [`heal_config`] / [`heal_intake`] / [`heal_select`] / [`heal_claims`] /
//!   [`heal_gate`] / [`heal_tick`] / [`heal_service`] — the self-healing loop:
//!   read a repository's open issues and pull requests, pick one, hand it to a
//!   coder session, and open a pull request only if the outcome contract AND an
//!   independent multi-model panel both pass. Never closes an issue; a human
//!   does. See `docs/proposals/self-healing-issue-loop.md`.
//!   issues on the (public) releases tracker: the *reporting* half of
//!   self-correction
//! - [`provenance`] — trust tiers for tracker text: every issue resolves to
//!   `runtime` / `maintainer` / `public` from its author account before its
//!   text is readable at all, and a `public` body can neither seed a session
//!   nor source an outcome contract. Live today for deduplication; the session
//!   and contract gates are the types the future tracker consumer must use
//!
//! ## Security boundary (read this before extending)
//!
//! The shell tool executes on the **host** with the daemon's privileges and
//! (deliberately) the real toolchain + network. The inspector chain blocks the
//! known-dangerous verbs (git push, sudo, destructive ops outside the
//! worktree, credential reads) plus every route that would *publish* the work
//! around the merge gate — the forge CLIs (`gh`, `glab`, `hub`) are cut to a
//! read-only allowlist and the registry publish subcommands (`npm publish`,
//! `cargo publish`, `docker push`) are denied — and the executor pins the
//! working directory to the worktree. But this is policy hardening, **not a
//! sandbox**: a model determined to misbehave can, e.g., pipe curl to sh
//! inside the worktree, or reach `gh` through a wrapper script.
//! The hard stops are the contract confirmation gate before any work starts
//! and the merge approval gate before anything reaches the user's repo.
//!
//! Anything that reads a tracker adds a second boundary: the report target is
//! **public**, so an issue body is attacker-controlled text. [`provenance`]
//! resolves every issue to a trust tier from its author account — never from
//! anything in the body — and its types are the reason a caller cannot read
//! tracker text without one.

pub mod ab;
pub mod ab_fixer;
pub mod ab_learnings;
pub mod ab_loop;
#[cfg(test)]
mod bench;
pub mod budget;
pub mod config;
pub mod contract;
pub mod declarative;
pub mod discuss;
pub mod external_loop;
pub mod fix_issues;
pub mod foreman_loop;
pub mod heal_claims;
pub mod heal_config;
/// End-to-end test of the healing loop over a real coder session. In-crate
/// rather than under `tests/` because `SessionSeed::from_trusted` is
/// `pub(in crate::coder)` on purpose; see the module's own docs.
#[cfg(test)]
mod heal_e2e;
pub mod heal_gate;
pub mod heal_intake;
pub mod heal_live;
pub mod heal_review;
pub mod heal_runner;
pub mod heal_select;
pub mod heal_service;
pub mod heal_tick;
/// Live trials — real GitHub permissions, real models, real delivery. All
/// `#[ignore]`d: they need credentials, a network, and real spend.
#[cfg(test)]
mod heal_trial;
pub mod merge;
pub mod native_loop;
pub mod no_change;
pub mod overlap;
pub mod policy;
pub mod project;
pub mod project_context;
pub mod provenance;
pub mod router;
pub mod rpc;
pub mod session;
pub mod shell_tool;
pub mod skill_memory;
#[cfg(test)]
pub(crate) mod test_cmds;

pub use ab::{
    attribute_round, run_ab_suite, AbArmRunner, AbCell, AbReport, AbTask, ArmEngine, ArmOutcome,
    ArmSpec, PairedStats, RoundAttribution,
};
pub use ab_fixer::{mutations_from_interventions, EvolutionAbFixer, HarnessApply};
pub use ab_learnings::{
    render_proposals, synthesize_proposals, Confidence, DurableFixProposal, ProposalKind,
};
pub use ab_loop::{
    run_improvement_loop, AbFixer, FixResult, ImprovementRun, LoopConfig, LoopStop, RoundRecord,
};
pub use config::{config_path, CoderConfig, DEFAULT_MAX_ITERATIONS};
pub use contract::{evaluate_contract, CheckResult, ContractCheck, OutcomeContract};
pub use discuss::{DiscussEvent, DiscussEventKind, DiscussionEntry, DiscussionMap};
pub use external_loop::{run_external_loop, CliInvoker, ExternalLoopConfig, LiveInvoker};
pub use fix_issues::{
    clears_reporting_bar, parse_signature_marker, proposal_signature, render_issue_body,
    render_report, report_proposals, signature_marker, GhIssues, IssueApi, ReportOutcome,
    ReportRecord, DEFAULT_REPORT_REPO,
};
pub use merge::{
    commit_to_main, deliver_pr, deliver_pr_with, publish_branch, publish_branch_headless,
    validate_branch_name, AzureDevOpsCli, CiCheck, CiState, CiSummary, DeliveryFailure,
    ForgeClient, ForgeError, ForgeKind, GhCli, GhError, GitHubApi, PrAction, PrDelivery,
    PrDeliveryOutcome, PrRecord, PrState, FORGE_OVERRIDE_ENV,
};
pub use native_loop::{
    model_tool_catalog, run_native_loop, LoopFailure, LoopOutcome, NativeLoopConfig,
};
pub use no_change::{
    baseline_completed, evaluate_nomination, head_commit, worktree_fingerprint,
    worktree_is_pristine, MutationLedger, NominationContext, NominationRefusal, NominationVerdict,
    MAX_FINDING_TEXT,
};
pub use project::{list_projects, resolve_or_create_project, slugify, CoderProject, ProjectKind};
pub use project_context::{
    agent_instructions, dot_car_knowledge, project_context, MAX_INSTRUCTIONS_BYTES,
    MAX_KNOWLEDGE_BYTES,
};
pub use provenance::{
    resolve_tier, ContractSource, GhPermissions, LocalSignatures, PermissionOracle,
    ProvenanceRecord, ProvenanceRefusal, ProvenanceTier, RawIssue, RepoPermission, SessionSeed,
    TieredIssue, UntrustedText, MAX_TIER_AGE,
};
pub use router::{
    detect_ready_agents, resolve_engine, DetectedAgent, EngineChoice, ResolvedEngine,
};
pub use session::{
    adopt_orphaned_sessions, default_state_dir, gc_sessions, needs_you_from, AdoptionOutcome,
    CancelFlag, CoderEvent, CoderEventKind, CoderSession, CoderState, EventEmitter, EventSink,
    NeedsYou, SessionRetention,
};
pub use shell_tool::WorktreeExecutor;
pub use skill_memory::{FailureSignature, RepairMemory};