Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Rust ai-agentsai-gatewayclaude-codecodexcoding-agentcost-optimizationdeepseekllm-gatewayllm-routerlocal-firstmodel-routingrusttask-routingtauri
//! One bounded execution over the small launcher. No production fallback for a missing backend.
use super::acp::{
AcpRunInput, AcpRunJournal, AcpRunOutcome, AcpTerminalCheckpoint,
run_acp_with_terminal_checkpoint,
};
use super::finalization::DelegationFinalizationLease;
use super::platform::*;
use super::profile::TaskSessionRoot;
use super::progress::{ProgressBatchWriter, ProgressCapture};
use hiroute_domain::delegation::DelegationErrorV1;
use std::fs;
use std::path::PathBuf;
use std::sync::Arc;
use std::time::Duration;
use tokio::time::{Instant, timeout, timeout_at};
pub const STOP_WAIT_MS: u64 = 10_000;
const CLAUDE_HISTORY_FLUSH_WAIT: Duration = Duration::from_secs(2);
const CLAUDE_HISTORY_QUIET: Duration = Duration::from_millis(200);
const CLAUDE_HISTORY_POLL: Duration = Duration::from_millis(25);
mod startup;
mod terminal;
use terminal::LiveTerminalCheckpoint;
#[derive(Clone, Copy)]
enum HistoryBaseline {
New,
Existing(u64),
Invalid,
}
struct ClaudeHistoryCheckpoint {
root: PathBuf,
baseline: HistoryBaseline,
}
impl ClaudeHistoryCheckpoint {
fn capture(
profile: &super::profile::CandidateWorkerProfile,
input: &AcpRunInput,
) -> Option<Self> {
if profile.identity_contract != super::acp::AcpNativeIdentityContract::ClaudeSessionV1 {
return None;
}
let baseline = match &input.session {
super::acp::AcpSessionStart::New => HistoryBaseline::New,
super::acp::AcpSessionStart::Load(binding)
| super::acp::AcpSessionStart::Resume(binding) => binding
.native_session_id
.as_deref()
.and_then(|id| claude_history_len(&profile.session_root, id))
.map_or(HistoryBaseline::Invalid, HistoryBaseline::Existing),
};
Some(Self {
root: profile.session_root.clone(),
baseline,
})
}
async fn wait_until_settled(&self, native_session_id: Option<&str>) -> bool {
let Some(native_session_id) = native_session_id else {
return false;
};
if matches!(self.baseline, HistoryBaseline::Invalid) {
return false;
}
let deadline = Instant::now() + CLAUDE_HISTORY_FLUSH_WAIT;
let mut observed = None;
let mut quiet_since = None;
loop {
let length = claude_history_len(&self.root, native_session_id);
let changed = length.is_some_and(|length| match self.baseline {
HistoryBaseline::New => length > 0,
HistoryBaseline::Existing(previous) => length > previous,
HistoryBaseline::Invalid => false,
});
if changed {
if observed == length {
let since = quiet_since.get_or_insert_with(Instant::now);
if since.elapsed() >= CLAUDE_HISTORY_QUIET {
return true;
}
} else {
observed = length;
quiet_since = Some(Instant::now());
}
} else {
observed = None;
quiet_since = None;
}
if Instant::now() >= deadline {
return false;
}
tokio::time::sleep(CLAUDE_HISTORY_POLL).await;
}
}
}
fn claude_history_len(root: &std::path::Path, native_session_id: &str) -> Option<u64> {
let transcript = TaskSessionRoot::native_transcript_path(
root,
hiroute_domain::delegation::WorkerHarnessV1::ClaudeCode,
native_session_id,
)
.ok()?;
fs::symlink_metadata(transcript)
.ok()
.filter(|metadata| metadata.is_file() && !metadata.file_type().is_symlink())
.map(|metadata| metadata.len())
}
#[derive(Clone)]
pub(crate) struct WorkerProgressWriter(Arc<dyn ProgressBatchWriter>);
impl WorkerProgressWriter {
pub(crate) fn new(writer: Arc<dyn ProgressBatchWriter>) -> Self {
Self(writer)
}
fn into_inner(self) -> Arc<dyn ProgressBatchWriter> {
self.0
}
/// A prelaunch check has no native output/capture task. Record only closed host facts.
pub(crate) fn dependency_failure(
&self,
failure: hiroute_domain::delegation::NativeDependencyFailureV1,
now_ms: i64,
) {
let action = if failure.reason.retryable() {
"Retry the same dependency selection after the temporary check failure."
} else {
"Check the selected native executable and its required capabilities."
};
let text = format!("[HiRoute] Worker dependency check failed: {failure}. {action}\n");
let _ = self.0.write_batch(&text, false, now_ms);
}
}
pub(crate) trait WorkerRunJournal: AcpRunJournal {
/// Production accepted runs expose an independent bounded progress writer. The default keeps
/// protocol-only journal fixtures free of persistence concerns.
fn progress_writer(&self) -> Option<WorkerProgressWriter> {
None
}
/// Production journals acquire the shared owned lease immediately before publishing a
/// terminal run. Probe journals have no durable continuation state and keep the default.
fn begin_finalization(&self) -> Option<DelegationFinalizationLease> {
None
}
/// Current authority check immediately before spawning (outside the admission gate).
fn before_launch(&self) -> Result<(), DelegationErrorV1>;
/// Persist the held-object locator before initialize/prompt. Failure triggers cleanup.
fn process_spawned(&self, identity: &WorkerProcessIdentity) -> Result<(), DelegationErrorV1>;
/// Immediately deny the run token and durably record termination intent before stopping.
fn stop_intent(&self) -> Result<(), DelegationErrorV1>;
/// Persist the result body relation and successful ACP completion before the launcher
/// revokes the run credential and stops its owned process scope.
fn completed(&self, outcome: &AcpRunOutcome) -> Result<(), DelegationErrorV1>;
/// Persist an uncertain/failed execution outcome before owned-process cleanup. A prompt is
/// never replayed merely because this method observes a disconnection.
fn execution_failed(&self, error: DelegationErrorV1) -> Result<(), DelegationErrorV1>;
/// A process may have started but the durable held-object binding failed. Record an explicit
/// unknown rather than claiming that launch never happened before cleanup runs.
fn spawned_unrecorded(&self) -> Result<(), DelegationErrorV1>;
}
pub struct WorkerRunResult {
pub execution: Result<AcpRunOutcome, DelegationErrorV1>,
pub identity: WorkerProcessIdentity,
pub stop: Option<WorkerStopEvidence>,
/// A persistence failure is not disguised as a successful cancellation.
pub stop_intent_error: Option<DelegationErrorV1>,
/// True when any adapter-specific native tail needed for a later Continue was durably quiet
/// before the owned process scope was stopped. Non-Claude profiles have no extra tail gate.
pub native_history_settled: bool,
/// Held from immediately before terminal publication until the executor has recorded stop
/// evidence and retained the exact native continuation materials.
pub(super) finalization: Option<DelegationFinalizationLease>,
}
pub(crate) async fn execute(
platform: &dyn WorkerPlatformPort,
request: WorkerLaunchRequest,
mut input: AcpRunInput,
journal: Arc<dyn WorkerRunJournal>,
) -> Result<WorkerRunResult, DelegationErrorV1> {
let platform_facts = match platform.capabilities(&request.profile) {
Ok(facts) => facts,
Err(error) => {
let _ = journal.execution_failed(error);
return Err(error);
}
};
if let Err(error) = request.profile.require_platform(&platform_facts) {
let _ = journal.execution_failed(error);
return Err(error);
}
if request.profile.cwd != input.cwd
|| request.profile.identity_contract != input.identity_contract
|| request.profile.session_meta != input.session_meta
{
let _ = journal.execution_failed(DelegationErrorV1::InvalidArguments);
return Err(DelegationErrorV1::InvalidArguments);
}
if input.cancellation.is_cancelled() {
let _ = journal.execution_failed(DelegationErrorV1::Cancelled);
return Err(DelegationErrorV1::Cancelled);
}
if input.deadline <= Instant::now() {
let _ = journal.execution_failed(DelegationErrorV1::DeadlineExceeded);
return Err(DelegationErrorV1::DeadlineExceeded);
}
let terminal_checkpoint = ClaudeHistoryCheckpoint::capture(&request.profile, &input)
.map(|history| Arc::new(LiveTerminalCheckpoint::new(journal.clone(), history)));
let startup = match startup::StartupPermit::acquire(
request.profile.native_initialization_root(),
input.deadline,
&input.cancellation,
)
.await
{
Ok(permit) => permit,
Err(error) => {
let _ = journal.execution_failed(error);
return Err(error);
}
};
// Waiting for another native initializer does not preserve stale launch authority.
journal.before_launch()?;
if let Err(error) = request
.profile
.validate_native_initialization(matches!(&input.session, super::acp::AcpSessionStart::New))
{
let _ = journal.execution_failed(error);
return Err(error);
}
// Dropped launch futures must finitely release acquired resources in the platform backend.
let launch_nonce = request.launch_nonce.clone();
let worker = tokio::select! {
biased;
_ = input.cancellation.cancelled() => {
let _ = journal.execution_failed(DelegationErrorV1::Cancelled);
return Err(DelegationErrorV1::Cancelled);
}
result = timeout_at(input.deadline, platform.launch(request)) => {
let result = match result {
Ok(result) => result,
Err(_) => {
let _ = journal.execution_failed(DelegationErrorV1::DeadlineExceeded);
return Err(DelegationErrorV1::DeadlineExceeded);
}
};
match result {
Ok(worker) => worker,
Err(error) => {
let _ = journal.execution_failed(error);
return Err(error);
}
}
}
};
if let Some(startup) = &startup {
startup.bind_process(&worker.identity);
}
let binding = if worker.identity.launch_nonce == launch_nonce {
journal.process_spawned(&worker.identity)
} else {
Err(DelegationErrorV1::Conflict)
};
let mut early_stop_error = None;
let mut progress_capture = None;
let execution = match binding {
Err(error) => {
let _ = journal.spawned_unrecorded();
Err(error)
}
Ok(()) => {
let acp_journal: Arc<dyn AcpRunJournal> = journal.clone();
let acp_journal = startup.as_ref().map_or_else(
|| acp_journal.clone(),
|startup| startup.journal(acp_journal.clone()),
);
progress_capture = journal
.progress_writer()
.map(WorkerProgressWriter::into_inner)
.map(ProgressCapture::start);
let progress_sink = progress_capture.as_ref().map(ProgressCapture::sink);
let outer_cancel = input.cancellation.clone();
let deadline = input.deadline;
let acp_cancel = tokio_util::sync::CancellationToken::new();
input.cancellation = acp_cancel.clone();
let future = run_acp_with_terminal_checkpoint(
worker.stdout,
worker.stdin,
input,
acp_journal,
progress_sink,
terminal_checkpoint
.as_ref()
.map(|checkpoint| checkpoint.clone() as Arc<dyn AcpTerminalCheckpoint>),
);
tokio::pin!(future);
tokio::select! {
biased;
_ = outer_cancel.cancelled() => {
// Failure remains visible through the idempotent stop_intent below.
early_stop_error = terminal_checkpoint.as_ref().map_or_else(
|| journal.stop_intent().err(),
|checkpoint| checkpoint.revoke(),
);
acp_cancel.cancel();
future.await
},
_ = tokio::time::sleep_until(deadline) => {
early_stop_error = terminal_checkpoint.as_ref().map_or_else(
|| journal.stop_intent().err(),
|checkpoint| checkpoint.revoke(),
);
acp_cancel.cancel();
future.await
},
result = &mut future => result,
}
}
};
let (execution, finalization, native_history_settled) = match terminal_checkpoint
.as_ref()
.and_then(|checkpoint| checkpoint.take_receipt())
{
Some(receipt) => (
receipt.execution,
receipt.finalization,
receipt.history_settled,
),
None => {
let finalization = journal.begin_finalization();
let execution = match execution {
Ok(outcome) => journal.completed(&outcome).map(|()| outcome),
Err(error) => {
let _ = journal.execution_failed(error);
Err(error)
}
};
let settled = execution.is_ok() && terminal_checkpoint.is_none();
(execution, finalization, settled)
}
};
let cleanup_stop_error = terminal_checkpoint.as_ref().map_or_else(
|| journal.stop_intent().err(),
|checkpoint| checkpoint.revoke(),
);
let stop_intent_error = early_stop_error.or(cleanup_stop_error);
// Claude's terminal callback already published/revoked and observed the exact
// native file before ACP EOF. Non-Claude/error/cancel paths retain the usual
// finalization above; only the outer lifecycle stops the held process scope.
// Even if persistence fails, do not abandon a held child. Return both pieces of evidence.
let stop = stop_owned(platform, &worker.identity).await;
if let Some(capture) = progress_capture {
capture.stop_and_flush().await;
}
Ok(WorkerRunResult {
execution,
identity: worker.identity,
stop,
stop_intent_error,
native_history_settled,
finalization,
})
}
pub async fn observe_owned(
platform: &dyn WorkerPlatformPort,
identity: &WorkerProcessIdentity,
) -> WorkerObservation {
timeout(
Duration::from_millis(STOP_WAIT_MS),
platform.observe(identity),
)
.await
.ok()
.and_then(Result::ok)
.unwrap_or(WorkerObservation::Unknown)
}
pub async fn stop_owned(
platform: &dyn WorkerPlatformPort,
identity: &WorkerProcessIdentity,
) -> Option<WorkerStopEvidence> {
let evidence = timeout(
Duration::from_millis(STOP_WAIT_MS),
platform.terminate(identity, STOP_WAIT_MS),
)
.await
.ok()
.and_then(Result::ok)?;
// Reject contradictory success evidence rather than release a live execution's slot.
if evidence.scope_stopped && !matches!(evidence.observation, WorkerObservation::Exited { .. }) {
return None;
}
startup::observe_stopped(identity, &evidence);
Some(evidence)
}
#[cfg(test)]
mod tests;