Skip to content

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.

fix: explain missing Codex adapter capability in Worker progress (#60)

澄潭79189c3adcbb
diff --git a/crates/daemon/src/delegation/acp/README.md b/crates/daemon/src/delegation/acp/README.md
index 37dca875..bd69215f 100644
--- a/crates/daemon/src/delegation/acp/README.md
+++ b/crates/daemon/src/delegation/acp/README.md
@@ -15,7 +15,7 @@ journal records prompt intent. Missing, ambiguous, rejected or unconfirmed model
selection is `CapabilityUnavailable`. Cancellation and deadline remain their own
errors. No approximate alias resolution or legacy RPC fallback is permitted.
-The supported wire behavior was inspected in `codex-acp` 1.1.5 and
+The model-selection wire behavior was inspected in `codex-acp` 1.1.5 and
`claude-agent-acp` 0.60.0. Both expose `configOptions` with `id: "model"` and
support `session/set_config_option`. Codex reports its base model separately from
the reasoning-effort selector. Claude can catch a failed resume model override
@@ -29,6 +29,13 @@ extension in their initialize response before a session or prompt is sent.
followed by `end_turn`; it cannot establish task success. The official 2.1.1
adapter advertises terminal failure metadata. Missing capability fails closed;
error-looking assistant prose is never parsed as a substitute terminal signal.
+The 1.1.5 model-selection observation above does not establish Worker compatibility.
+On a missing capability, this owner writes a fixed `[HiRoute]` explanation to the
+existing bounded progress capture, naming `codex-acp`, the capability and the
+update/reselect action. The lifecycle flushes it after owned-process cleanup, so
+ordinary Worker progress reads can retrieve it after reopen. It is not a model
+result and contains no adapter-supplied text. The public error remains
+`CapabilityUnavailable`; no version allowlist or dependency preflight is added.
The Rust ACP dependency provides typed config options and a typed setter; its
current v1 schema does not retain legacy `models` response fields. A legacy
diff --git a/crates/daemon/src/delegation/acp/mod.rs b/crates/daemon/src/delegation/acp/mod.rs
index 7e9cb7e9..6a16b122 100644
--- a/crates/daemon/src/delegation/acp/mod.rs
+++ b/crates/daemon/src/delegation/acp/mod.rs
@@ -113,7 +113,7 @@ where
let updates = Arc::new(Mutex::new(Updates::default()));
let notifications = updates.clone();
let notification_journal = journal.clone();
- let notification_progress = progress;
+ let notification_progress = progress.clone();
let permissions = updates.clone();
let permission_journal = journal.clone();
let permission_cancellation = input.cancellation.clone();
@@ -189,7 +189,7 @@ where
.connect_with(
transport::bounded_transport(reader, writer),
async move |connection: ConnectionTo<Agent>| {
- Ok(run_session(connection, input, journal, updates).await)
+ Ok(run_session(connection, input, journal, updates, progress).await)
},
);
tokio::pin!(connected);
@@ -217,6 +217,7 @@ async fn run_session(
input: AcpRunInput,
journal: Arc<dyn AcpRunJournal>,
updates: Arc<Mutex<Updates>>,
+ progress: Option<ProgressSink>,
) -> Result<AcpRunOutcome, DelegationErrorV1> {
let initialized = phase(
&input.cancellation,
@@ -230,6 +231,11 @@ async fn run_session(
if input.identity_contract == AcpNativeIdentityContract::CodexThreadV1
&& !advertises_session_failure(initialized.meta.as_ref())
{
+ // The adapter has already spawned. Use the lifecycle's bounded progress capture,
+ // which is flushed after owned-process cleanup, without inventing a model result.
+ if let Some(progress) = progress.as_ref() {
+ progress.push("[HiRoute] The selected codex-acp adapter does not advertise the required AIR v1 sessionFailure capability. Update the adapter to a version supporting this capability, select it again in Worker dependencies, and submit the task again.\n");
+ }
return Err(DelegationErrorV1::CapabilityUnavailable);
}
journal.initialized();
diff --git a/crates/daemon/src/delegation/lifecycle/tests.rs b/crates/daemon/src/delegation/lifecycle/tests.rs
index 3cd0e09b..b6fa60ea 100644
--- a/crates/daemon/src/delegation/lifecycle/tests.rs
+++ b/crates/daemon/src/delegation/lifecycle/tests.rs
@@ -9,6 +9,8 @@ use std::sync::Mutex;
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio_util::sync::CancellationToken;
+#[cfg(unix)]
+mod codex_capability;
mod startup;
#[derive(Default)]
@@ -16,6 +18,7 @@ struct Journal(
Mutex<Vec<&'static str>>,
Option<Arc<crate::delegation::finalization::DelegationFinalization>>,
std::sync::atomic::AtomicBool,
+ Option<WorkerProgressWriter>,
);
impl AcpRunJournal for Journal {
fn session_bound(&self, _: &AcpSessionBinding) -> Result<(), DelegationErrorV1> {
@@ -34,6 +37,10 @@ impl AcpRunJournal for Journal {
}
}
impl WorkerRunJournal for Journal {
+ fn progress_writer(&self) -> Option<WorkerProgressWriter> {
+ self.3.clone()
+ }
+
fn begin_finalization(
&self,
) -> Option<crate::delegation::finalization::DelegationFinalizationLease> {
@@ -428,6 +435,7 @@ async fn terminal_publication_lease_survives_until_the_executor_receives_the_res
Mutex::default(),
Some(Arc::clone(&finalization)),
Default::default(),
+ None,
));
let backend = Fixture {
journal: Arc::clone(&journal),
diff --git a/crates/daemon/src/delegation/lifecycle/tests/codex_capability.rs b/crates/daemon/src/delegation/lifecycle/tests/codex_capability.rs
new file mode 100644
index 00000000..75d8b061
--- /dev/null
+++ b/crates/daemon/src/delegation/lifecycle/tests/codex_capability.rs
@@ -0,0 +1,142 @@
+use super::*;
+use crate::delegation::local_worker::LocalWorkerPlatform;
+use crate::delegation::progress::ObservationProgressWriter;
+use hiroute_domain::WorkspaceId;
+use hiroute_observation::managed_text::{
+ ManagedTextProgressRead, ManagedTextProgressTarget, ManagedTextScope,
+};
+use hiroute_observation::{DigestAuthority, LocalObservationStore};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+#[tokio::test]
+async fn spawned_codex_capability_failure_survives_cleanup_and_progress_reopen() {
+ for continued in [false, true] {
+ for supported in [false, true] {
+ let (mut request, mut input, fixture) = inputs();
+ let script = fixture.path().join("adapter.py");
+ let transcript = fixture.path().join("requests");
+ std::fs::write(&script, r#"import json, sys
+supported = sys.argv[1] == 'supported'
+for line in sys.stdin:
+ request = json.loads(line)
+ method = request['method']
+ with open(sys.argv[2], 'a') as log:
+ log.write(method + '\n')
+ modes = {'currentModeId':'agent-full-access','availableModes':[{'id':'agent-full-access','name':'Autonomous'}]}
+ if method == 'initialize':
+ result = {'protocolVersion':1,'agentCapabilities':{'loadSession':True},'agentInfo':{'name':'PRIVATE_ADAPTER_OUTPUT','version':'PRIVATE_VERSION'}}
+ if supported:
+ result['_meta'] = {'jetbrains':{'air':{'version':1,'capabilities':['sessionFailure']}}}
+ elif method == 'session/new':
+ result = {'sessionId':'native-session','modes':modes}
+ elif method == 'session/load':
+ assert request['params']['sessionId'] == 'native-session'
+ result = {'modes':modes}
+ elif method == 'session/set_mode':
+ result = {}
+ elif method == 'session/prompt':
+ result = {'stopReason':'end_turn'}
+ else:
+ raise AssertionError(method)
+ print(json.dumps({'jsonrpc':'2.0','id':request['id'],'result':result}), flush=True)
+"#).unwrap();
+ request.profile.executable = "/usr/bin/python3".into();
+ request.profile.args = vec![
+ script,
+ if supported {
+ "supported"
+ } else {
+ "unsupported"
+ }
+ .into(),
+ transcript.clone(),
+ ];
+ let now_ms = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .unwrap()
+ .as_millis() as i64;
+ request.deadline_unix_ms = now_ms as u64 + 5_000;
+ input.deadline = Instant::now() + Duration::from_secs(5);
+ if continued {
+ input.session = AcpSessionStart::Load(AcpSessionBinding {
+ acp_session_id: "native-session".into(),
+ native_session_id: Some("native-session".into()),
+ });
+ }
+ let observation = tempfile::tempdir().unwrap();
+ let store = Arc::new(
+ LocalObservationStore::open(observation.path(), DigestAuthority::new([9; 32]))
+ .unwrap(),
+ );
+ let target = ManagedTextProgressTarget {
+ scope: ManagedTextScope {
+ workspace_id: WorkspaceId::default(),
+ task_id: "capability-task".into(),
+ run_id: "capability-run".into(),
+ },
+ created_at_ms: now_ms,
+ };
+ let journal = Arc::new(Journal(
+ Mutex::default(),
+ None,
+ Default::default(),
+ Some(WorkerProgressWriter::new(Arc::new(
+ ObservationProgressWriter::new(Arc::clone(&store), target.clone()),
+ ))),
+ ));
+ let private_root = request.profile.private_root.clone();
+ let result = execute(
+ &LocalWorkerPlatform::default(),
+ request,
+ input,
+ journal.clone(),
+ )
+ .await
+ .unwrap();
+ assert!(result.stop.unwrap().scope_stopped);
+ assert!(result.stop_intent_error.is_none());
+ assert!(!private_root.exists());
+ let methods = std::fs::read_to_string(transcript).unwrap();
+ let events = journal.0.lock().unwrap().clone();
+ assert!(events.contains(&"spawned"));
+ assert!(events.contains(&"revoke"));
+ drop(journal);
+ drop(store);
+ let reopened =
+ LocalObservationStore::open(observation.path(), DigestAuthority::new([9; 32]))
+ .unwrap();
+ let progress = reopened
+ .managed_text_progress_read(&target, None, 4096)
+ .unwrap();
+ if supported {
+ assert!(result.execution.unwrap().text.is_empty());
+ assert!(methods.contains("session/prompt"));
+ assert!(methods.contains(if continued {
+ "session/load"
+ } else {
+ "session/new"
+ }));
+ assert!(matches!(progress, ManagedTextProgressRead::Missing { .. }));
+ } else {
+ assert!(matches!(
+ result.execution,
+ Err(DelegationErrorV1::CapabilityUnavailable)
+ ));
+ assert_eq!(methods, "initialize\n");
+ assert!(events.contains(&"failed"));
+ assert!(!events.contains(&"prompt") && !events.contains(&"completed"));
+ let ManagedTextProgressRead::Available(page) = progress else {
+ panic!(
+ "missing adapter capability must leave readable Worker progress after cleanup"
+ );
+ };
+ assert_eq!(page.text.matches("[HiRoute]").count(), 1);
+ assert!(page.text.contains("codex-acp"));
+ assert!(page.text.contains("sessionFailure"));
+ assert!(page.text.contains("Update") && page.text.contains("select"));
+ assert!(!page.text.contains("PRIVATE_"));
+ assert!(!page.text.contains("fixture-token"));
+ }
+ }
+ }
+}
diff --git a/docs/code-map/worker-context.md b/docs/code-map/worker-context.md
index 7c0a3339..b5e1cc60 100644
--- a/docs/code-map/worker-context.md
+++ b/docs/code-map/worker-context.md
@@ -103,6 +103,12 @@ separate evidence; an acceptance pin is not a production version allowlist.
## State and lifetime
+Codex adapters missing AIR `sessionFailure` fail during actual initialize, before
+session creation/load. The [ACP owner](../../crates/daemon/src/delegation/acp/README.md)
+adds an actionable `[HiRoute]` reason to the existing Worker progress window;
+[lifecycle](../../crates/daemon/src/delegation/lifecycle.rs) flushes it after owned
+process cleanup. This host explanation is separate from the model result.
+
The task root owns context descriptors and exact-session bindings. Run roots own
temporary launch materials and credentials. Borrowed HOME/config/history remain
native-owned; Continue reads the original descriptor rather than today's service
diff --git a/docs/standalone-cli.md b/docs/standalone-cli.md
index a2cc3057..9750bfc0 100644
--- a/docs/standalone-cli.md
+++ b/docs/standalone-cli.md
@@ -533,6 +533,17 @@ hiroute worker executors --output json
hiroute worker plans --output json
```
+Codex Workers require the selected `codex-acp` adapter to advertise AIR
+`sessionFailure` during initialization. The inspected 1.1.5 adapter lacks this
+capability; 2.1.1 advertises it. HiRoute checks the capability, not a version
+allowlist. If a task fails with `CapabilityUnavailable`, use
+`hiroute worker read --run RUN_ID` to inspect its saved progress. A `[HiRoute]`
+message identifies this missing capability and explains how to recover: update
+the selected adapter, select its paths again in Worker dependencies, then submit
+the task again. Use a new submission key for a new run; replaying the previous
+key returns the existing failed run. Discovery/selection is not a compatibility
+preflight and does not install or update the adapter.
+
Set routing-editor `delegation_enabled` to `true`, add
`"work":{"harness":"codex_cli","protocol":"responses"}`, and publish again. Then submit,
locate, wait for, and read the task:
diff --git a/docs/standalone-cli.zh-CN.md b/docs/standalone-cli.zh-CN.md
index 8094916b..e1086f64 100644
--- a/docs/standalone-cli.zh-CN.md
+++ b/docs/standalone-cli.zh-CN.md
@@ -493,6 +493,14 @@ hiroute worker executors --output json
hiroute worker plans --output json
```
+Codex Worker 要求所选 `codex-acp` adapter 在初始化时声明 AIR `sessionFailure`
+能力。已核对的 1.1.5 缺少该能力,2.1.1 声明了该能力;HiRoute 检查能力,不使用版本
+白名单。如果任务以 `CapabilityUnavailable` 失败,可通过
+`hiroute worker read --run RUN_ID` 查看已保存的进展。缺少此能力时,`[HiRoute]`
+提示会说明原因和处理办法:更新所选 adapter,在 Worker 依赖配置中重新选择路径,再重新
+提交任务。新运行使用新的 submission key;重放旧 key 只会返回原来的失败运行。
+发现和选择不是兼容性预检查,也不会安装或更新 adapter。
+
将路由 editor 的 `delegation_enabled` 设为 `true`,并加入
`"work":{"harness":"codex_cli","protocol":"responses"}` 后重新发布。再提交、定位、等待和读取: