arabica-cli 0.13.1

Arabica: a terminal coding agent with a fullscreen TUI, ACP support for Zed, and one-shot runs
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
//! Drives the real, compiled `arabica acp` binary as a subprocess against
//! a mock OpenAI-compatible HTTP server, over its actual stdin/stdout --
//! not the in-process `Channel::duplex()` harness `crates/arabica-cli/src/acp/mod.rs`'s
//! own `round_trip` tests use.
//!
//! That in-process harness proves the handler wiring, the spawn/observer/permission
//! concurrency, and the stop-reason mapping. It cannot prove that a real subprocess
//! started the way an editor starts one, talking real newline-delimited JSON-RPC over
//! real OS pipes, to a real HTTP round trip, produces a wire-legal multi-turn
//! conversation. That is what this test is for: two prompts in the same session, so
//! the second model call's request body is exactly the kind of place the B4 bug
//! class (`crates/arabica-runtime/src/short_memory.rs`'s `exact_transcript_entries`)
//! would resurface if a regression ever reintroduced it -- the mock server itself
//! rejects an illegal message sequence, rather than the test inspecting the body
//! after the fact, so a regression fails loudly at the point it would also break a
//! real provider.

use std::path::PathBuf;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};
use std::time::Duration;

use agent_client_protocol::schema::ProtocolVersion;
use agent_client_protocol::schema::v1::{
    ContentBlock, InitializeRequest, NewSessionRequest, PermissionOptionKind, PromptRequest,
    RequestPermissionOutcome, RequestPermissionRequest, RequestPermissionResponse,
    SelectedPermissionOutcome, StopReason,
};
use agent_client_protocol::{ByteStreams, Client, Responder};
use axum::extract::State;
use axum::http::StatusCode;
use axum::response::{IntoResponse, Json, Response};
use axum::routing::post;
use serde_json::Value;
use tokio::io::AsyncBufReadExt;
use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};

#[derive(Clone, Default)]
struct MockState {
    requests: Arc<Mutex<Vec<Value>>>,
    rejected: Arc<AtomicUsize>,
}

/// Every assistant message with `tool_calls` must be followed immediately
/// by exactly that many `tool`-role messages carrying matching
/// `tool_call_id`s, with nothing else wedged in between. This is the wire
/// contract `HistoryProjection::ExactTranscript` exists to guarantee across
/// a second `session/prompt` in the same session; a violation here is a
/// real B4-class regression, not a test-harness quirk.
fn find_sequencing_violation(messages: &[Value]) -> Option<String> {
    let mut index = 0;
    while index < messages.len() {
        let message = &messages[index];
        let tool_call_ids: Vec<&str> = message
            .get("tool_calls")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
            .filter_map(|call| call["id"].as_str())
            .collect();
        if tool_call_ids.is_empty() {
            index += 1;
            continue;
        }
        for (offset, expected_id) in tool_call_ids.iter().enumerate() {
            let followup_index = index + 1 + offset;
            let Some(followup) = messages.get(followup_index) else {
                return Some(format!(
                    "assistant tool_calls at index {index} has no message at {followup_index} to answer it"
                ));
            };
            if followup["role"] != "tool" {
                return Some(format!(
                    "expected a tool-role message at index {followup_index} answering the assistant tool_calls at index {index}, found role {:?}",
                    followup["role"]
                ));
            }
            if followup["tool_call_id"].as_str() != Some(*expected_id) {
                return Some(format!(
                    "message at index {followup_index} has tool_call_id {:?}, expected {expected_id:?}",
                    followup["tool_call_id"]
                ));
            }
        }
        index += 1 + tool_call_ids.len();
    }
    None
}

fn tool_call_response(call_id: &str, name: &str, arguments: &str) -> Value {
    serde_json::json!({
        "choices": [{
            "message": {
                "role": "assistant",
                "content": null,
                "tool_calls": [{
                    "id": call_id,
                    "type": "function",
                    "function": {"name": name, "arguments": arguments}
                }]
            },
            "finish_reason": "tool_calls"
        }]
    })
}

fn text_response(text: &str) -> Value {
    serde_json::json!({
        "choices": [{
            "message": {"role": "assistant", "content": text},
            "finish_reason": "stop"
        }]
    })
}

async fn chat_completions(State(state): State<MockState>, Json(body): Json<Value>) -> Response {
    let call_index = {
        let mut requests = state.requests.lock().expect("requests lock poisoned");
        requests.push(body.clone());
        requests.len()
    };
    let messages = body["messages"].as_array().cloned().unwrap_or_default();
    if let Some(violation) = find_sequencing_violation(&messages) {
        state.rejected.fetch_add(1, Ordering::SeqCst);
        return (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({"error": {"message": violation}})),
        )
            .into_response();
    }

    let response = match call_index {
        1 => tool_call_response(
            "call-1",
            "write_file",
            r#"{"path":"note.txt","content":"hello from the mock model"}"#,
        ),
        2 => text_response("created note.txt"),
        3 => text_response(
            "I created note.txt with \"hello from the mock model\" in the previous turn.",
        ),
        other => {
            state.rejected.fetch_add(1, Ordering::SeqCst);
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({"error": {"message": format!("unexpected call number {other}")}})),
            )
                .into_response();
        }
    };
    Json(response).into_response()
}

fn temp_dir(label: &str) -> PathBuf {
    let unique = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .expect("clock is valid")
        .as_nanos();
    let root = std::env::temp_dir().join(format!("structure-acp-e2e-{label}-{unique}"));
    std::fs::create_dir_all(&root).expect("dir is created");
    root
}

#[tokio::test]
async fn two_prompt_turns_over_the_real_binary_stay_wire_legal_and_execute_for_real() {
    run_two_prompt_turns(false).await;
}

#[tokio::test]
async fn image_input_survives_tool_continuation_next_turn_and_persistence() {
    run_two_prompt_turns(true).await;
}

async fn run_two_prompt_turns(with_image: bool) {
    const PNG: &str = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=";
    let state = MockState::default();
    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
        .await
        .expect("mock endpoint binds");
    let address = listener.local_addr().expect("mock address exists");
    let app = axum::Router::new()
        .route("/v1/chat/completions", post(chat_completions))
        .with_state(state.clone());
    tokio::spawn(async move {
        axum::serve(listener, app)
            .await
            .expect("mock endpoint serves");
    });

    let workspace_root = temp_dir("workspace");
    let arabica_home = temp_dir("home");
    std::fs::write(
        arabica_home.join("config.toml"),
        "[providers.mock]\napi_key_env = 'ARABICA_PROVIDER_MOCK_API_KEY'\nbase_url = 'http://unused/v1'\n\n[models.default]\nprovider = 'mock'\nmodel_id = 'test-model'\n\n[blend]\ndefault_model = 'default'\ntool_call_capable_models = ['default']\n",
    )
    .unwrap();

    let mut child = tokio::process::Command::new(env!("CARGO_BIN_EXE_arabica"))
        .arg("acp")
        .env("ARABICA_PROVIDER_MOCK_API_KEY", "test-key")
        .env("ARABICA__BASE_URL", format!("http://{address}/v1"))
        .env("ARABICA_HOME", &arabica_home)
        .stdin(std::process::Stdio::piped())
        .stdout(std::process::Stdio::piped())
        .stderr(std::process::Stdio::piped())
        .kill_on_drop(true)
        .spawn()
        .expect("spawn the real structure binary");

    let stdin = child.stdin.take().expect("stdin is piped");
    let stdout = child.stdout.take().expect("stdout is piped");
    let stderr = child.stderr.take().expect("stderr is piped");
    let stderr_lines = Arc::new(Mutex::new(Vec::<String>::new()));
    tokio::spawn({
        let stderr_lines = stderr_lines.clone();
        async move {
            let mut lines = tokio::io::BufReader::new(stderr).lines();
            while let Ok(Some(line)) = lines.next_line().await {
                stderr_lines
                    .lock()
                    .expect("stderr lines lock poisoned")
                    .push(line);
            }
        }
    });

    let transport = ByteStreams::new(stdin.compat_write(), stdout.compat());
    let workspace_for_client = workspace_root.clone();
    let round_trip = Client
        .builder()
        .name("e2e-test-client")
        .on_receive_request(
            async move |request: RequestPermissionRequest,
                        responder: Responder<RequestPermissionResponse>,
                        _connection| {
                // write_file is Ask by default (acp::permission::default_policy):
                // a real editor's user would see and answer this prompt, so the
                // test stands in for them rather than the agent silently
                // executing an unapproved write.
                let allow_once = request
                    .options
                    .iter()
                    .find(|option| option.kind == PermissionOptionKind::AllowOnce)
                    .expect("the agent must offer an allow-once option")
                    .option_id
                    .clone();
                responder.respond(RequestPermissionResponse::new(
                    RequestPermissionOutcome::Selected(SelectedPermissionOutcome::new(allow_once)),
                ))
            },
            agent_client_protocol::on_receive_request!(),
        )
        .connect_with(transport, async move |cx| {
            let initialized = cx
                .send_request(InitializeRequest::new(ProtocolVersion::V1))
                .block_task()
                .await?;
            assert!(initialized.agent_capabilities.prompt_capabilities.image);
            let session = cx
                .send_request(NewSessionRequest::new(workspace_for_client))
                .block_task()
                .await?;
            let session_id = session.session_id.to_string();
            let mut prompt = vec![ContentBlock::from("create note.txt with some content")];
            if with_image {
                prompt.clear();
                prompt.push(ContentBlock::Image(
                    agent_client_protocol::schema::v1::ImageContent::new(PNG, "image/png"),
                ));
            }
            let first = cx
                .send_request(PromptRequest::new(session.session_id.clone(), prompt))
                .block_task()
                .await?;
            let second = cx
                .send_request(PromptRequest::new(
                    session.session_id,
                    vec![ContentBlock::from("what did you just create?")],
                ))
                .block_task()
                .await?;
            Ok((first.stop_reason, second.stop_reason, session_id))
        });

    let (first_stop_reason, second_stop_reason, session_id) =
        tokio::time::timeout(Duration::from_secs(8), round_trip)
            .await
            .unwrap_or_else(|_| {
                panic!(
                    "the round trip did not finish in time; stderr so far: {:?}",
                    stderr_lines.lock().expect("stderr lines lock poisoned")
                )
            })
            .unwrap_or_else(|error| {
                panic!(
                    "the round trip returned a JSON-RPC error: {error}; stderr: {:?}",
                    stderr_lines.lock().expect("stderr lines lock poisoned")
                )
            });

    let exit_status = tokio::time::timeout(Duration::from_secs(5), child.wait())
        .await
        .expect("the child exits promptly once its stdin closes")
        .expect("waiting on the child does not itself fail");

    assert_eq!(
        state.rejected.load(Ordering::SeqCst),
        0,
        "the mock server rejected at least one request as wire-illegal; stderr: {:?}",
        stderr_lines.lock().expect("stderr lines lock poisoned")
    );
    assert_eq!(
        state.requests.lock().expect("requests lock poisoned").len(),
        3,
        "expected exactly 3 model calls: the tool call, its follow-up, and the second turn"
    );
    assert_eq!(first_stop_reason, StopReason::EndTurn);
    assert_eq!(second_stop_reason, StopReason::EndTurn);
    assert!(
        exit_status.success(),
        "the binary must exit 0 once the connection ends cleanly"
    );

    let written = std::fs::read_to_string(workspace_root.join("note.txt"))
        .expect("write_file actually ran against the real filesystem");
    assert_eq!(written, "hello from the mock model");

    // The ACP session id is exactly the stringified Arabica session id
    // (`acp::AcpState::new_session`), so this round-trips it back rather
    // than re-deriving anything the store itself would not have used.
    let workspace_id = arabica_cli::host::workspace_id_for(&workspace_root);
    let stored = arabica_adapters::SqliteSessionStore::read_session(
        &arabica_home,
        &workspace_id,
        &arabica_protocol::SessionId::new(session_id),
    )
    .expect("the real binary persisted this session and it is readable back");
    assert!(
        matches!(
            stored.events.first().map(|envelope| &envelope.event),
            Some(arabica_protocol::Event::SessionCreated { .. })
        ),
        "the first persisted event must be session.created, got {:?}",
        stored.events.first()
    );
    assert!(
        stored.events.len() > 5,
        "two prompt turns, one with a tool call, must persist more than a handful of events, got {}",
        stored.events.len()
    );

    if with_image {
        // The image appears exactly once on its own turn's initial call and
        // tool follow-up, even though the current input also has a canonical
        // event. The next turn sends a note in its place, not the bytes.
        let requests = state.requests.lock().unwrap();
        let image_urls = |request: &serde_json::Value| -> Vec<serde_json::Value> {
            request["messages"]
                .as_array()
                .unwrap()
                .iter()
                .flat_map(|message| message["content"].as_array().into_iter().flatten())
                .filter(|part| part["type"] == "image_url")
                .cloned()
                .collect()
        };
        for request in &requests[..2] {
            let urls = image_urls(request);
            assert_eq!(urls.len(), 1);
            assert_eq!(
                urls[0]["image_url"]["url"],
                format!("data:image/png;base64,{PNG}")
            );
        }
        let next_turn = &requests[2];
        assert!(
            image_urls(next_turn).is_empty(),
            "earlier images are not resent"
        );
        assert!(
            next_turn["messages"]
                .as_array()
                .unwrap()
                .iter()
                .any(|message| message["role"] == "user"
                    && message["content"]
                        .as_str()
                        .is_some_and(|text| text.contains("1 image attached here earlier"))),
            "the earlier turn keeps a note that an image was attached"
        );
        assert!(stored.events.iter().any(|envelope| matches!(
            &envelope.event, arabica_protocol::Event::MessageAccepted { images, .. }
                if images.len() == 1 && images[0].data_base64 == PNG
        )));
    }

    std::fs::remove_dir_all(&workspace_root).ok();
    std::fs::remove_dir_all(&arabica_home).ok();
}

// The binary test above only ever exercises `find_sequencing_violation`
// against a well-formed conversation (`HistoryProjection::ExactTranscript`
// is correct, so it never gets the chance to detect anything). These prove
// the detector itself actually catches the B4 pattern it exists to guard
// against, rather than that assumption resting solely on the happy path
// above never tripping it.
mod sequencing_violation_tests {
    use super::find_sequencing_violation;
    use serde_json::json;

    #[test]
    fn a_well_formed_tool_call_and_result_pair_is_not_a_violation() {
        let messages = vec![
            json!({"role": "user", "content": "do something"}),
            json!({
                "role": "assistant",
                "tool_calls": [{"id": "call-1", "type": "function", "function": {"name": "write_file", "arguments": "{}"}}]
            }),
            json!({"role": "tool", "tool_call_id": "call-1", "content": "ok"}),
            json!({"role": "assistant", "content": "done"}),
        ];
        assert_eq!(find_sequencing_violation(&messages), None);
    }

    #[test]
    fn the_b4_pattern_is_detected_a_message_wedged_between_the_call_and_its_result() {
        // The exact shape B4 produced: a system/observation message lands
        // between an assistant tool_calls message and the tool message
        // that answers it.
        let messages = vec![
            json!({"role": "user", "content": "do something"}),
            json!({
                "role": "assistant",
                "tool_calls": [{"id": "call-1", "type": "function", "function": {"name": "write_file", "arguments": "{}"}}]
            }),
            json!({"role": "system", "content": "a wedged observation, not a tool result"}),
            json!({"role": "tool", "tool_call_id": "call-1", "content": "ok"}),
        ];
        let violation =
            find_sequencing_violation(&messages).expect("must detect the wedged message");
        assert!(violation.contains("index 2"));
    }

    #[test]
    fn a_mismatched_tool_call_id_is_detected() {
        let messages = vec![
            json!({
                "role": "assistant",
                "tool_calls": [{"id": "call-1", "type": "function", "function": {"name": "write_file", "arguments": "{}"}}]
            }),
            json!({"role": "tool", "tool_call_id": "call-2", "content": "answers the wrong call"}),
        ];
        assert!(find_sequencing_violation(&messages).is_some());
    }

    #[test]
    fn a_tool_call_with_no_answer_at_all_is_detected() {
        let messages = vec![json!({
            "role": "assistant",
            "tool_calls": [{"id": "call-1", "type": "function", "function": {"name": "write_file", "arguments": "{}"}}]
        })];
        assert!(find_sequencing_violation(&messages).is_some());
    }

    #[test]
    fn multiple_tool_calls_in_one_turn_each_need_their_own_matching_result_in_order() {
        let messages = vec![json!({
            "role": "assistant",
            "tool_calls": [
                {"id": "call-1", "type": "function", "function": {"name": "read_file", "arguments": "{}"}},
                {"id": "call-2", "type": "function", "function": {"name": "read_file", "arguments": "{}"}}
            ]
        })];
        assert!(
            find_sequencing_violation(&messages).is_some(),
            "two tool_calls with zero following tool messages must be flagged"
        );

        let messages = vec![
            json!({
                "role": "assistant",
                "tool_calls": [
                    {"id": "call-1", "type": "function", "function": {"name": "read_file", "arguments": "{}"}},
                    {"id": "call-2", "type": "function", "function": {"name": "read_file", "arguments": "{}"}}
                ]
            }),
            json!({"role": "tool", "tool_call_id": "call-1", "content": "a"}),
            json!({"role": "tool", "tool_call_id": "call-2", "content": "b"}),
        ];
        assert_eq!(find_sequencing_violation(&messages), None);
    }
}