The design language that makes your AI harness better at design.
JavaScript
//! JS: live-server.mjs, the in-memory session state and queue mechanics:
//! pending events, parked polls, SSE clients, leases and their timers, agent
//! phases, manual-edit activity. Routes live in `live_server`; the manual
//! apply controller in `manual_edits::apply`.
use crate::manifests::RootsManifest;
use crate::paths::live_dir;
use crate::preflight::{build_generation_preflight, compact_error};
use crate::session::{SessionStore, GENERATION_FENCED_SESSION_PHASES};
use crate::util::{iso_now, jsp, now_ms, Env};
use crate::vocabulary::VARIANT_PROGRESS_CHECKPOINT_REASONS;
use impeccable_context::target_args::TargetOptions;
use serde_json::{json, Map, Value};
use std::collections::HashMap;
use std::sync::mpsc::{channel, Receiver, Sender};
use std::sync::{Arc, Mutex, Weak};
use std::time::{Duration, Instant};
pub const DEFAULT_POLL_TIMEOUT: i64 = 600_000;
pub const SSE_HEARTBEAT_INTERVAL_MS: u64 = 30_000;
pub const CHAT_POLL_FRESHNESS_MS: i64 = 60_000;
pub const POLL_LEASE_EXPIRY_TIMER_GRACE_MS: i64 = 2;
pub const EXIT_TIMER_MS: u64 = 8000;
pub const PREFLIGHT_TIMEOUT_MS: u64 = 15_000;
pub struct PendingEntry {
pub event: Map<String, Value>,
pub lease_until: i64,
pub seq: i64,
}
pub struct ParkedPoll {
pub id: u64,
pub tx: Sender<Value>,
pub lease_ms: i64,
pub types: Option<Vec<String>>,
/// `GET /poll?id=`: lease only the events of that session (the
/// generate verb picks up its own event without touching another's).
pub event_id: Option<String>,
}
pub struct SseClient {
pub id: u64,
pub tx: Sender<String>,
/// The overlay's per-page-load id (`/events?clientId=`), so a disconnect
/// can retire its word in any agent-target roll call it took part in.
pub agent_client_id: Option<String>,
}
/// One overlay's roll-call report on an agent target: its busy state and why.
/// A generate event refused because its agent target is spoken for; see
/// `ServerState::agent_target_refusal`.
pub struct AgentTargetRefusal {
/// The session that answered the request, when the verdict carried one.
pub session_id: Option<String>,
}
pub struct AgentTargetReport {
pub client_id: String,
pub state: Value,
pub reason: Value,
/// The overlay's resolution verdict when it declined because its page
/// cannot resolve the target (`reason: no_match`).
pub result: Option<Value>,
}
/// A held-open `POST /agent-target` (the `generate` command): resolved by
/// `POST /agent-target-result`, by a complete busy roll call, by its timeout,
/// or by shutdown. The claim lease decides which overlay acts.
pub struct AgentTargetPending {
pub tx: Sender<Value>,
/// The `agent_target` SSE payload, replayed to overlays that connect late.
pub payload: Value,
pub owner: Option<String>,
pub claimed_until: i64,
/// The overlay most recently granted the lease, kept when the lease
/// lapses or its page goes away: its Go may still land late, and it is
/// the only page besides the current holder allowed to open the session.
pub last_holder: Option<String>,
pub reports: Vec<AgentTargetReport>,
pub timer_gen: u64,
/// While every report says `no_match`, the roll call stays open until
/// this instant: a page whose element mounts late can still claim.
pub resolve_grace_until: Option<i64>,
}
/// One pre-apply file snapshot entry (`{ exists, content }`).
#[derive(Clone, Debug)]
pub struct FileSnapshot {
pub exists: bool,
pub content: String,
}
pub struct ApplyDeferred {
pub tx: Sender<Result<Value, String>>,
pub event: Map<String, Value>,
pub batch: Value,
pub page_url: Value,
pub rollback_snapshot: Vec<(String, FileSnapshot)>,
pub cwd: String,
pub timer_gen: u64,
}
pub struct TimedOutApply {
pub batch: Value,
pub rollback_snapshot: Vec<(String, FileSnapshot)>,
pub cwd: String,
}
pub struct ServerState {
pub token: String,
pub port: i64,
pub cwd: String,
pub env: Env,
pub roots: Option<RootsManifest>,
pub sse_clients: Vec<SseClient>,
pub pending_events: Vec<PendingEntry>,
pub pending_polls: Vec<ParkedPoll>,
pub next_event_seq: i64,
pub last_agent_polling_broadcast: Option<bool>,
pub exit_timer_gen: u64,
pub exit_timer_active: bool,
pub session_dir: Option<String>,
pub store: SessionStore,
pub lease_timer_gen: u64,
pub lease_timer_active: bool,
pub manual_edit_activity: Option<Value>,
pub next_manual_edit_seq: i64,
pub pending_apply_deferreds: Vec<(String, ApplyDeferred)>,
/// Held-open agent targets keyed by targetId, in arrival order.
pub pending_agent_targets: Vec<(String, AgentTargetPending)>,
pub next_agent_target_timer_gen: u64,
/// Every agent target already answered, oldest first (bounded), with
/// the session that answered it when the verdict carried one. A
/// generate event naming a target is welcome only while that target is
/// pending without a rival lease, or when it comes from the session
/// that answered it; anything else, including a target this record no
/// longer holds, is refused, so eviction can never reopen a request.
pub resolved_agent_targets: Vec<(String, Option<String>)>,
/// The generate lane asked this helper to keep the overlay's global bar
/// out of the way (`live --no-live-bar` or an agent target carrying
/// `hideLiveBar`). Helper-wide and for its lifetime: every connected
/// tab hides on the broadcast, every later connection on `connected`.
pub hide_live_bar: bool,
pub last_poll_at: i64,
pub timed_out_apply_ids: Vec<(String, TimedOutApply)>,
pub next_poll_id: u64,
pub next_client_id: u64,
pub next_apply_timer_gen: u64,
pub shutting_down: bool,
/// Set once `shutdown` ran its cleanup (it may be invoked from the /stop
/// handler and again by the accept loop).
pub cleaned_up: bool,
pub log_tx: Sender<(bool, String)>,
pub debug_manual_edit_events: bool,
pub self_ref: Weak<Mutex<ServerState>>,
/// Preflight source-resolution cache: target signature -> source file.
pub source_resolution_cache: HashMap<String, String>,
pub detect_script: String,
}
pub type Shared = Arc<Mutex<ServerState>>;
pub fn now_i64() -> i64 {
now_ms() as i64
}
pub fn lock(shared: &Shared) -> std::sync::MutexGuard<'_, ServerState> {
match shared.lock() {
Ok(g) => g,
Err(poisoned) => poisoned.into_inner(),
}
}
/// JS: eventPriority(event)
pub fn event_priority(event: &Map<String, Value>) -> i64 {
match event.get("type").and_then(|t| t.as_str()) {
Some("accept") | Some("discard") | Some("exit") => 0,
Some("manual_edit_apply") | Some("steer") | Some("carbonize_cleanup") => 1,
Some("generate") => 2,
_ => 3,
}
}
fn is_leased_at(entry: &PendingEntry, now: i64) -> bool {
entry.lease_until != 0 && entry.lease_until > now
}
/// JS: selectAvailablePendingEvent(entries, { now, types }) -> index
pub fn select_available_pending_event(
entries: &[PendingEntry],
now: i64,
types: Option<&[String]>,
event_id: Option<&str>,
) -> Option<usize> {
let mut best: Option<usize> = None;
for (i, entry) in entries.iter().enumerate() {
if is_leased_at(entry, now) {
continue;
}
if let Some(wanted) = event_id {
if entry.event.get("id").and_then(|v| v.as_str()) != Some(wanted) {
continue;
}
}
if let Some(allowed) = types {
let ty = entry
.event
.get("type")
.and_then(|t| t.as_str())
.unwrap_or("");
if !allowed.iter().any(|t| t == ty) {
continue;
}
}
match best {
None => best = Some(i),
Some(b) => {
let (pb, sb) = (event_priority(&entries[b].event), entries[b].seq);
let (pi, si) = (event_priority(&entry.event), entry.seq);
if pi < pb || (pi == pb && si < sb) {
best = Some(i);
}
}
}
}
best
}
fn ev_str<'a>(m: &'a Map<String, Value>, k: &str) -> Option<&'a str> {
m.get(k).and_then(|v| v.as_str())
}
pub fn truthy(v: Option<&Value>) -> bool {
crate::event_validation::truthy(v)
}
impl ServerState {
pub fn log_out(&self, s: &str) {
let _ = self.log_tx.send((false, s.to_string()));
}
pub fn log_err(&self, s: &str) {
let _ = self.log_tx.send((true, s.to_string()));
}
/// JS: chatAgentLikelyActive()
pub fn chat_agent_likely_active(&self) -> bool {
if !self.pending_polls.is_empty() {
return true;
}
if self.last_poll_at == 0 {
return false;
}
now_i64() - self.last_poll_at < CHAT_POLL_FRESHNESS_MS
}
/// JS: enqueueEvent(event)
pub fn enqueue_event(&mut self, mut event: Map<String, Value>) {
strip_poller_owned_event_fields(&mut event);
let id = event.get("id").filter(|v| truthy(Some(v))).cloned();
if let Some(id) = &id {
let ty = event.get("type").cloned().unwrap_or(Value::Null);
let is_mount_failed = ty.as_str() == Some("variant_mount_failed");
let dup = self.pending_events.iter().any(|entry| {
entry.event.get("id") == Some(id)
&& entry.event.get("type").cloned().unwrap_or(Value::Null) == ty
&& (!is_mount_failed || entry.event.get("variant") == event.get("variant"))
});
if dup {
return;
}
}
let seq = self.next_event_seq;
self.next_event_seq += 1;
self.pending_events.push(PendingEntry {
event,
lease_until: 0,
seq,
});
self.flush_pending_polls();
}
/// JS: restorePendingEventsFromStore()
pub fn restore_pending_events_from_store(&mut self) {
for snapshot in self.store.list_active_sessions() {
if let Some(Value::Object(pe)) = snapshot.get("pendingEvent") {
self.enqueue_event(pe.clone());
}
}
}
pub fn find_available_pending_event(
&self,
types: Option<&[String]>,
event_id: Option<&str>,
) -> Option<usize> {
select_available_pending_event(&self.pending_events, now_i64(), types, event_id)
}
/// JS: recordAgentPhase(id, phase, details)
pub fn record_agent_phase(&mut self, id: &str, phase: &str, details: &[(&str, Value)]) {
if id.is_empty() {
return;
}
let mut event = Map::new();
event.insert("type".into(), json!("agent_phase"));
event.insert("id".into(), json!(id));
event.insert("phase".into(), json!(phase));
event.insert("at".into(), json!(now_i64()));
for (k, v) in details {
event.insert((*k).to_string(), v.clone());
}
let _ = self.store.append_event(&Value::Object(event.clone()));
self.broadcast(&Value::Object(event));
}
/// JS: acknowledgePendingEvent(id, sourceEventType) -> acknowledged event
pub fn acknowledge_pending_event(
&mut self,
id: Option<&str>,
source_event_type: Option<&str>,
) -> Option<Map<String, Value>> {
let id = id.filter(|s| !s.is_empty())?;
let idx = self.pending_events.iter().position(|entry| {
ev_str(&entry.event, "id") == Some(id)
&& (source_event_type.is_none()
|| ev_str(&entry.event, "type") == source_event_type)
})?;
let acknowledged = self.pending_events.remove(idx).event;
self.schedule_lease_flush();
self.broadcast_agent_polling_if_changed();
Some(acknowledged)
}
/// JS: releasePendingEvent(id, sourceEventType)
pub fn release_pending_event(
&mut self,
id: Option<&str>,
source_event_type: Option<&str>,
) -> Option<Map<String, Value>> {
let id = id?;
let entry = self.pending_events.iter_mut().find(|entry| {
ev_str(&entry.event, "id") == Some(id)
&& (source_event_type.is_none()
|| ev_str(&entry.event, "type") == source_event_type)
})?;
entry.lease_until = 0;
let ev = entry.event.clone();
self.schedule_lease_flush();
Some(ev)
}
/// JS: retirePendingGeneration(id)
pub fn retire_pending_generation(&mut self, id: Option<&str>) -> usize {
let Some(id) = id.filter(|s| !s.is_empty()) else {
return 0;
};
let before = self.pending_events.len();
self.pending_events.retain(|entry| {
!(ev_str(&entry.event, "id") == Some(id)
&& ev_str(&entry.event, "type") == Some("generate"))
});
let retired = before - self.pending_events.len();
if retired > 0 {
self.schedule_lease_flush();
self.broadcast_agent_polling_if_changed();
}
retired
}
/// JS: findPendingEventById(id, sourceEventType)
pub fn find_pending_event_by_id(
&self,
id: Option<&str>,
source_event_type: Option<&str>,
) -> Option<&Map<String, Value>> {
let id = id.filter(|s| !s.is_empty())?;
self.pending_events
.iter()
.find(|entry| {
ev_str(&entry.event, "id") == Some(id)
&& (source_event_type.is_none()
|| ev_str(&entry.event, "type") == source_event_type)
})
.map(|e| &e.event)
}
/// JS: cancelQueuedAnonymousExitEvents()
pub fn cancel_queued_anonymous_exit_events(&mut self) -> usize {
let before = self.pending_events.len();
self.pending_events.retain(|entry| {
!(ev_str(&entry.event, "type") == Some("exit") && !truthy(entry.event.get("id")))
});
let removed = before - self.pending_events.len();
if removed > 0 {
self.schedule_lease_flush();
self.broadcast_agent_polling_if_changed();
}
removed
}
/// JS: scheduleLeaseFlush()
pub fn schedule_lease_flush(&mut self) {
// clearTimeout
self.lease_timer_gen += 1;
self.lease_timer_active = false;
let now = now_i64();
let next = self
.pending_events
.iter()
.map(|e| e.lease_until)
.filter(|l| *l > now)
.min();
let Some(next) = next else {
return;
};
let gen = self.lease_timer_gen;
self.lease_timer_active = true;
let delay = (next - now + POLL_LEASE_EXPIRY_TIMER_GRACE_MS).max(0) as u64;
let weak = self.self_ref.clone();
std::thread::spawn(move || {
std::thread::sleep(Duration::from_millis(delay));
if let Some(shared) = weak.upgrade() {
let mut st = lock(&shared);
if st.lease_timer_active && st.lease_timer_gen == gen {
st.lease_timer_active = false;
st.flush_pending_polls();
st.broadcast_agent_polling_if_changed();
}
}
});
}
/// JS: flushPendingPolls(). Leases run on their own thread (the JS
/// resolved the poll when the async lease settled).
pub fn flush_pending_polls(&mut self) {
let mut changed = false;
loop {
if self.pending_polls.is_empty() {
break;
}
let mut found: Option<(usize, usize)> = None;
let now = now_i64();
for (pi, poll) in self.pending_polls.iter().enumerate() {
if let Some(ei) = select_available_pending_event(
&self.pending_events,
now,
poll.types.as_deref(),
poll.event_id.as_deref(),
) {
found = Some((pi, ei));
break;
}
}
let Some((pi, ei)) = found else {
self.schedule_lease_flush();
self.broadcast_agent_polling_if_changed();
return;
};
let poll = self.pending_polls.remove(pi);
// Claim synchronously (JS: entry.leaseUntil set before any await).
let lease_ms = poll.lease_ms;
self.pending_events[ei].lease_until = now_i64() + lease_ms;
let entry_seq = self.pending_events[ei].seq;
let entry_event = self.pending_events[ei].event.clone();
let weak = self.self_ref.clone();
std::thread::spawn(move || {
let Some(shared) = weak.upgrade() else {
return;
};
let event = lease_event(&shared, entry_seq, entry_event, lease_ms);
{
let mut st = lock(&shared);
st.last_poll_at = now_i64();
}
let _ = poll.tx.send(Value::Object(event));
});
changed = true;
}
self.schedule_lease_flush();
if changed {
self.broadcast_agent_polling_if_changed();
}
}
/// JS: agentPollingConnected()
pub fn agent_polling_connected(&self) -> bool {
!self.pending_polls.is_empty()
}
/// JS: broadcastAgentPollingIfChanged()
pub fn broadcast_agent_polling_if_changed(&mut self) {
let connected = self.agent_polling_connected();
if self.last_agent_polling_broadcast == Some(connected) {
return;
}
self.last_agent_polling_broadcast = Some(connected);
self.broadcast(&json!({ "type": "agent_polling", "connected": connected }));
}
/// JS: broadcast(msg)
/// Flip the helper-wide bar preference and tell every connected tab.
pub fn set_live_bar_hidden(&mut self, hidden: bool) {
if self.hide_live_bar == hidden {
return;
}
self.hide_live_bar = hidden;
self.broadcast(&json!({ "type": "live_bar", "hidden": hidden }));
}
pub fn broadcast(&mut self, msg: &Value) {
let data = format!(
"data: {}\n\n",
serde_json::to_string(msg).unwrap_or_else(|_| "null".into())
);
for client in &self.sse_clients {
let _ = client.tx.send(data.clone());
}
}
/// JS: recordManualEditActivity(type, details)
pub fn record_manual_edit_activity(&mut self, ty: &str, details: Map<String, Value>) -> Value {
let mut entry = Map::new();
entry.insert("seq".into(), json!(self.next_manual_edit_seq));
self.next_manual_edit_seq += 1;
entry.insert("type".into(), json!(ty));
entry.insert("ts".into(), json!(iso_now()));
for (k, v) in details {
entry.insert(k, v);
}
let v = Value::Object(entry);
self.manual_edit_activity = Some(v.clone());
if self.debug_manual_edit_events {
let file = jsp::join(&[&live_dir(&self.cwd, &self.env), "manual-edit-events.jsonl"]);
if let Some(parent) = std::path::Path::new(&file).parent() {
let _ = std::fs::create_dir_all(parent);
}
use std::io::Write;
if let Ok(mut f) = std::fs::OpenOptions::new()
.create(true)
.append(true)
.open(&file)
{
let _ = f.write_all(
format!("{}\n", serde_json::to_string(&v).unwrap_or_default()).as_bytes(),
);
}
}
self.broadcast(&v);
v
}
/// JS: getManualEditStatus()
pub fn manual_edit_status(&self) -> Value {
let (total, per_page) = crate::manual_edits::buffer::count_by_page(&self.cwd, &self.env);
json!({
"totalCount": total,
"perPage": per_page,
"lastActivity": self.manual_edit_activity.clone().unwrap_or(Value::Null),
})
}
/// JS: summarizePendingEventForStatus(entry)
pub fn summarize_pending_event_for_status(&self, entry: &PendingEntry) -> Value {
let event = &entry.event;
let mut s = Map::new();
s.insert("id".into(), event.get("id").cloned().unwrap_or(Value::Null));
s.insert(
"type".into(),
event.get("type").cloned().unwrap_or(Value::Null),
);
// JSON.stringify drops undefined: an event without id/type would
// omit the key entirely.
if !event.contains_key("id") {
s.shift_remove("id");
}
if !event.contains_key("type") {
s.shift_remove("type");
}
s.insert("leased".into(), json!(is_leased_at(entry, now_i64())));
s.insert(
"leaseUntil".into(),
if entry.lease_until != 0 {
json!(entry.lease_until)
} else {
Value::Null
},
);
if ev_str(event, "type") == Some("manual_edit_apply") {
let or_null = |k: &str| match event.get(k) {
Some(v) if truthy(Some(v)) => v.clone(),
_ => Value::Null,
};
s.insert("pageUrl".into(), or_null("pageUrl"));
s.insert("chunk".into(), or_null("chunk"));
s.insert("repair".into(), or_null("repair"));
s.insert("evidencePath".into(), or_null("evidencePath"));
let agent_action = match event.get("agentAction") {
Some(v) if truthy(Some(v)) => v.clone(),
_ => {
crate::manual_edits::apply::build_manual_apply_agent_action(ev_str(event, "id"))
}
};
s.insert("agentAction".into(), agent_action);
let id = ev_str(event, "id").unwrap_or("");
let deferred_batch = self
.pending_apply_deferreds
.iter()
.find(|(k, _)| k == id)
.map(|(_, d)| d.batch.clone())
.filter(|b| truthy(Some(b)));
let batch = deferred_batch
.unwrap_or_else(|| event.get("batch").cloned().unwrap_or(Value::Null));
s.insert(
"manualApplySummary".into(),
crate::manual_edits::apply::summarize_manual_apply_event(event, &batch, &self.cwd),
);
}
Value::Object(s)
}
/// JS: activeSessionSummaries()
pub fn active_session_summaries(&self) -> Vec<Value> {
self.store
.list_active_sessions()
.iter()
.map(summarize_active_session_for_client)
.collect()
}
/// JS: the /events GET handler's timer arming: after the last SSE client
/// leaves, queue an anonymous `exit` 8 s later if still nobody.
pub fn arm_exit_timer(&mut self) {
self.exit_timer_gen += 1;
let gen = self.exit_timer_gen;
self.exit_timer_active = true;
let weak = self.self_ref.clone();
std::thread::spawn(move || {
std::thread::sleep(Duration::from_millis(EXIT_TIMER_MS));
if let Some(shared) = weak.upgrade() {
let mut st = lock(&shared);
if st.exit_timer_active && st.exit_timer_gen == gen {
st.exit_timer_active = false;
if st.sse_clients.is_empty() {
let mut ev = Map::new();
ev.insert("type".into(), json!("exit"));
st.enqueue_event(ev);
}
}
}
});
}
pub fn clear_exit_timer(&mut self) {
self.exit_timer_gen += 1;
self.exit_timer_active = false;
}
/// Register a parked poll; returns (id, receiver).
pub fn park_poll(
&mut self,
lease_ms: i64,
types: Option<Vec<String>>,
event_id: Option<String>,
) -> (u64, Receiver<Value>) {
let (tx, rx) = channel();
let id = self.next_poll_id;
self.next_poll_id += 1;
self.pending_polls.push(ParkedPoll {
id,
tx,
lease_ms,
types,
event_id,
});
self.broadcast_agent_polling_if_changed();
self.schedule_lease_flush();
(id, rx)
}
/// Remove a parked poll by id; true when it was still parked.
pub fn remove_poll(&mut self, id: u64) -> bool {
let before = self.pending_polls.len();
self.pending_polls.retain(|p| p.id != id);
before != self.pending_polls.len()
}
/// Register an SSE client; returns (id, receiver). An overlay that
/// connects after an agent target was broadcast (a reload mid-request is
/// the common case) joins its roll call: every pending target is replayed
/// to it, so it claims or declines like the others instead of silently
/// widening the count the roll call is judged against.
pub fn add_sse_client(
&mut self,
agent_client_id: Option<String>,
) -> (u64, Receiver<String>, Sender<String>) {
let (tx, rx) = channel();
let id = self.next_client_id;
self.next_client_id += 1;
for (_, pending) in &self.pending_agent_targets {
let _ = tx.send(format!(
"data: {}\n\n",
serde_json::to_string(&pending.payload).unwrap_or_else(|_| "null".into())
));
}
self.sse_clients.push(SseClient {
id,
tx: tx.clone(),
agent_client_id,
});
(id, rx, tx)
}
/// Remove an SSE client; when none remain arm the exit timer (JS
/// `req.on('close')`). A departed overlay's word no longer counts in any
/// agent-target roll call. The overlay, not the connection, is the
/// participant: an EventSource reconnect opens a replacement connection
/// under the same page-level clientId before the old one is seen to
/// close, so its word is retired only once no connection carries that
/// id, while every roll call is still re-judged against the connections
/// that remain.
pub fn remove_sse_client(&mut self, id: u64) {
let before = self.sse_clients.len();
let agent_client_id = self
.sse_clients
.iter()
.find(|c| c.id == id)
.and_then(|c| c.agent_client_id.clone());
self.sse_clients.retain(|c| c.id != id);
if before != self.sse_clients.len() {
let still_connected = agent_client_id
.as_deref()
.map(|cid| self.sse_clients.iter().any(|c| c.agent_client_id.as_deref() == Some(cid)))
.unwrap_or(false);
self.drop_agent_target_client(if still_connected { None } else { agent_client_id.as_deref() });
if self.sse_clients.is_empty() {
self.clear_exit_timer();
self.arm_exit_timer();
}
}
}
/// Whether a connection carries this overlay's clientId. True as well
/// while any connection sent none (an older overlay build): that
/// overlay cannot be told apart from the id in hand.
fn overlay_connected(&self, client_id: &str) -> bool {
self.sse_clients.iter().any(|c| match c.agent_client_id.as_deref() {
Some(cid) => cid == client_id,
None => true,
})
}
/// Connected overlays for a roll call: one per distinct clientId, plus
/// every connection that sent none (an older overlay build), so a
/// reconnect's momentary duplicate connection never waits on a second
/// report from the same tab.
pub fn connected_overlay_count(&self) -> usize {
let mut ids: Vec<&str> = Vec::new();
let mut anonymous = 0;
for c in &self.sse_clients {
match c.agent_client_id.as_deref() {
Some(cid) => {
if !ids.contains(&cid) {
ids.push(cid);
}
}
None => anonymous += 1,
}
}
ids.len() + anonymous
}
// ---------------------------------------------------------------------
// Agent-initiated element targeting (the `generate` command)
// ---------------------------------------------------------------------
//
// POST /agent-target lets the AGENT start a variant session: the server
// pushes an `agent_target` SSE message, the overlay resolves the selector,
// scrolls to the element, enters the same picked state a user click
// produces, and fires the normal Go pipeline. The HTTP response is held
// open until the overlay POSTs /agent-target-result (or the timeout
// fires), so the CLI gets a synchronous verdict. No session exists until
// the browser's own generate event creates one.
/// Browser must answer an agent_target push within this window. The env
/// override exists for tests; real sessions keep the default.
pub fn agent_target_timeout_ms(&self) -> u64 {
env_positive_ms(&self.env, "IMPECCABLE_AGENT_TARGET_TIMEOUT_MS").unwrap_or(15_000)
}
/// A granted claim is a lease, not a lock: if the winning tab dies before
/// posting its result (reload, crash), the lease lapses and a surviving
/// tab's retry rescues the request instead of letting it wait out the
/// browser timeout. The lease comfortably exceeds a healthy winner's
/// worst case (claim RTT + smooth-scroll settle + Go, under 2s).
pub fn agent_target_lease_ms(&self) -> i64 {
env_positive_ms(&self.env, "IMPECCABLE_AGENT_TARGET_CLAIM_LEASE_MS")
.map(|v| v as i64)
.unwrap_or(3_000)
}
/// A page's `no_match` is a provisional word: an element can mount after
/// the page first looked (a route still rendering, an HMR swap). When
/// every connected overlay says `no_match`, the roll call stays open for
/// this long after the first such report, so a page that keeps watching
/// can still claim; a busy report answers at once regardless.
pub fn agent_target_resolve_grace_ms(&self) -> i64 {
env_positive_ms(&self.env, "IMPECCABLE_AGENT_TARGET_RESOLVE_GRACE_MS")
.map(|v| v as i64)
.unwrap_or(3_000)
}
/// Hold a new agent target: mint its id, broadcast the push, arm the
/// timeout. Returns the id and the receiver the route blocks on.
pub fn register_agent_target(&mut self, mut payload: Map<String, Value>) -> (String, Receiver<Value>) {
let target_id = crate::random::random_id8();
payload.insert("targetId".into(), json!(target_id));
// JS spread order: type, targetId, then the request fields.
let mut ordered = Map::new();
ordered.insert("type".into(), json!("agent_target"));
ordered.insert("targetId".into(), json!(target_id));
for (k, v) in payload {
if k != "type" && k != "targetId" {
ordered.insert(k, v);
}
}
let payload = Value::Object(ordered);
let (tx, rx) = channel();
self.next_agent_target_timer_gen += 1;
let timer_gen = self.next_agent_target_timer_gen;
self.pending_agent_targets.push((
target_id.clone(),
AgentTargetPending {
tx,
payload: payload.clone(),
owner: None,
claimed_until: 0,
last_holder: None,
reports: Vec::new(),
timer_gen,
resolve_grace_until: None,
},
));
self.broadcast(&payload);
let timeout_ms = self.agent_target_timeout_ms();
let weak = self.self_ref.clone();
let id = target_id.clone();
std::thread::spawn(move || {
std::thread::sleep(Duration::from_millis(timeout_ms));
if let Some(shared) = weak.upgrade() {
let mut st = lock(&shared);
let Some((_, pending)) = st
.pending_agent_targets
.iter()
.find(|(k, p)| *k == id && p.timer_gen == timer_gen)
else {
return;
};
let verdict = if pending.reports.is_empty() {
json!({ "ok": false, "error": "browser_timeout", "timeoutMs": timeout_ms })
} else {
agent_target_verdict_from_reports(pending)
};
st.resolve_agent_target(&id, verdict);
}
});
(target_id, rx)
}
/// A result post is only honored from the overlay that holds the
/// target's claim: every connected overlay knows the target id and the
/// helper token, so the token alone must not let a bystander answer
/// for the winner. Ok(delivered) when the holder answered (or nothing
/// awaited the target); Err(reason) when the target is pending but the
/// caller is not its holder.
pub fn resolve_agent_target_as_holder(
&mut self,
target_id: &str,
client_id: &str,
result: Value,
) -> Result<bool, &'static str> {
if let Some((_, pending)) = self
.pending_agent_targets
.iter()
.find(|(k, _)| k == target_id)
{
match &pending.owner {
Some(owner) if owner == client_id => {}
Some(_) => return Err("not_holder"),
None => return Err("unclaimed"),
}
}
Ok(self.resolve_agent_target(target_id, result))
}
/// Deliver a verdict to the held request; false when nothing awaits it.
pub fn resolve_agent_target(&mut self, target_id: &str, result: Value) -> bool {
let Some(pos) = self
.pending_agent_targets
.iter()
.position(|(k, _)| k == target_id)
else {
return false;
};
let (_, pending) = self.pending_agent_targets.remove(pos);
let session = if result.get("ok") == Some(&Value::Bool(true)) {
result
.get("sessionId")
.and_then(Value::as_str)
.map(str::to_string)
} else {
None
};
self.resolved_agent_targets
.push((target_id.to_string(), session));
if self.resolved_agent_targets.len() > 256 {
self.resolved_agent_targets.remove(0);
}
let _ = pending.tx.send(result);
true
}
/// Why a generate event naming `envelope.targetId`, sent by
/// `envelope.clientId` under `session_id`, must not open a session:
/// the target is still pending and this page is not its holder (another
/// page holds the lease, or held it last, or nobody claimed it); the
/// request was already answered, with a different session or with none
/// (a timeout or a failure verdict the CLI has already reported); or the
/// helper neither holds nor remembers the target (never issued here, or
/// long since evicted from the bounded record). None only when the
/// event is welcome: the holder's own Go (its lease may have lapsed, or
/// its page gone away, as long as no rescuer claimed since), or the
/// answering session's own event.
pub fn agent_target_refusal(
&self,
envelope: &Map<String, Value>,
session_id: Option<&str>,
) -> Option<AgentTargetRefusal> {
let target_id = envelope.get("targetId").and_then(Value::as_str)?;
let client_id = envelope
.get("clientId")
.and_then(Value::as_str)
.unwrap_or("");
if let Some((_, pending)) = self
.pending_agent_targets
.iter()
.find(|(k, _)| k == target_id)
{
let is_holder = match &pending.owner {
Some(owner) => owner == client_id,
// Lease handed back or the page gone: only the page that
// held it last may still land its Go.
None => pending.last_holder.as_deref() == Some(client_id) && !client_id.is_empty(),
};
return if is_holder { None } else { Some(AgentTargetRefusal { session_id: None }) };
}
let Some((_, answered_by)) = self
.resolved_agent_targets
.iter()
.rev()
.find(|(t, _)| t == target_id)
else {
return Some(AgentTargetRefusal { session_id: None });
};
if answered_by.as_deref() == session_id && session_id.is_some() {
return None;
}
Some(AgentTargetRefusal {
session_id: answered_by.clone(),
})
}
/// Every connected overlay has declined: answer busy now, not at the
/// timeout. Judged against the connections of this moment, so it runs
/// whenever a report lands and whenever an overlay leaves.
pub fn maybe_complete_agent_target_roll_call(&mut self, target_id: &str) {
let connected = self.connected_overlay_count();
let now = now_i64();
let verdict = self
.pending_agent_targets
.iter()
.find(|(k, _)| k == target_id)
.and_then(|(_, p)| {
if p.owner.is_some() || p.reports.is_empty() || p.reports.len() < connected {
return None;
}
let all_no_match = p.reports.iter().all(|r| r.reason.as_str() == Some("no_match"));
if all_no_match && p.resolve_grace_until.map(|until| now < until).unwrap_or(false) {
// Every page says no_match, but one may still be
// watching a late mount: the grace timer re-runs this
// check when it lapses.
return None;
}
Some(agent_target_verdict_from_reports(p))
});
if let Some(verdict) = verdict {
self.resolve_agent_target(target_id, verdict);
}
}
/// Each overlay's first `no_match` word extends the resolution grace by
/// the full window, so a page that reports after another page's grace
/// lapsed still gets its watch; the roll call is re-judged when the
/// latest grace lapses (the lapse alone never resolves; the check
/// re-reads the reports, so a claim or a busy word in between takes
/// precedence). The target's timeout bounds the sum.
fn arm_agent_target_resolve_grace(&mut self, target_id: &str) {
let grace_ms = self.agent_target_resolve_grace_ms();
let Some((_, pending)) = self
.pending_agent_targets
.iter_mut()
.find(|(k, _)| k == target_id)
else {
return;
};
let until = now_i64() + grace_ms;
if pending.resolve_grace_until.map(|u| u >= until).unwrap_or(false) {
return;
}
pending.resolve_grace_until = Some(until);
let weak = self.self_ref.clone();
let id = target_id.to_string();
std::thread::spawn(move || {
std::thread::sleep(Duration::from_millis(grace_ms.max(0) as u64 + 5));
if let Some(shared) = weak.upgrade() {
lock(&shared).maybe_complete_agent_target_roll_call(&id);
}
});
}
/// A disconnected overlay's word no longer counts: drop its busy report,
/// hand back a lease it held (a rescuer's next claim is granted at once
/// instead of after the lease lapses), and re-judge each roll call
/// against the overlays that remain.
pub fn drop_agent_target_client(&mut self, client_id: Option<&str>) {
let ids: Vec<String> = self
.pending_agent_targets
.iter()
.map(|(k, _)| k.clone())
.collect();
for id in ids {
if let Some(cid) = client_id {
if let Some((_, p)) = self.pending_agent_targets.iter_mut().find(|(k, _)| *k == id) {
p.reports.retain(|r| r.client_id != cid);
if p.owner.as_deref() == Some(cid) {
p.owner = None;
p.claimed_until = 0;
}
}
}
self.maybe_complete_agent_target_roll_call(&id);
}
}
/// Roll call plus a first-wins lease. Every connected overlay claims once.
/// A busy tab claims with eligible:false and is only counted: the moment
/// every connected overlay has reported busy, the held request answers
/// `busy` without waiting on a timer or guessing about a slower idle tab.
/// An eligible tab is granted when nobody holds the lease, when it
/// already holds it (a renew, which the holder does right before it
/// fires Go, so a lapsed lease can never leave two tabs acting), or when
/// the previous holder's lease lapsed without a result (a rescue).
/// Unknown or resolved targets deny and say so (`pending: false`), which
/// ends a rescuer's retry loop. Returns the response body.
pub fn claim_agent_target(
&mut self,
target_id: &str,
client_id: &str,
eligible: bool,
state: Value,
reason: Value,
result: Option<Value>,
) -> Value {
let lease_ms = self.agent_target_lease_ms();
let now = now_i64();
let reporter_connected = eligible || self.overlay_connected(client_id);
let Some((_, pending)) = self
.pending_agent_targets
.iter_mut()
.find(|(k, _)| k == target_id)
else {
return json!({ "ok": true, "granted": false, "pending": false });
};
if !eligible {
// A report under an id no connection carries any more (the page
// unloaded between the broadcast and this claim landing) is not
// a participant's word: recorded, it could complete the roll
// call, or set its verdict, against the overlays that remain.
// An eligible claim is left alone: a lease a departed page holds
// lapses and a rescuer takes it, while refusing it would also
// refuse the renew a live overlay sends inside an EventSource
// reconnect gap, whose Go is still welcome.
if !reporter_connected {
return json!({ "ok": true, "granted": false, "pending": true });
}
let reason_is_no_match = reason.as_str() == Some("no_match");
// Only an overlay's first no_match word extends the grace: its
// re-reports while watching must not keep the roll call open.
let first_no_match_from_client = !pending
.reports
.iter()
.any(|r| r.client_id == client_id && r.reason.as_str() == Some("no_match"));
pending.reports.retain(|r| r.client_id != client_id);
pending.reports.push(AgentTargetReport {
client_id: client_id.to_string(),
state,
reason,
result,
});
// A holder that turned busy hands the lease back, so the roll
// call can complete and an eligible tab's retry is granted at
// once instead of waiting for the lease to lapse.
if pending.owner.as_deref() == Some(client_id) {
pending.owner = None;
pending.claimed_until = 0;
}
if reason_is_no_match && first_no_match_from_client {
self.arm_agent_target_resolve_grace(target_id);
}
self.maybe_complete_agent_target_roll_call(target_id);
// `pending` tells a declining overlay whether to keep watching
// for a change of its word (an element that mounts late, a
// session that ends); false once the roll call or a result
// resolved the request.
let still_pending = self.pending_agent_targets.iter().any(|(k, _)| k == target_id);
return json!({ "ok": true, "granted": false, "pending": still_pending });
}
// An eligible claim is the client's latest word: drop any earlier
// busy report, so a busy verdict only ever counts tabs still busy.
pending.reports.retain(|r| r.client_id != client_id);
let granted = pending.owner.is_none()
|| pending.owner.as_deref() == Some(client_id)
|| pending.claimed_until <= now;
if granted {
pending.owner = Some(client_id.to_string());
pending.last_holder = Some(client_id.to_string());
pending.claimed_until = now + lease_ms;
}
json!({ "ok": true, "granted": granted, "pending": true })
}
/// JS: generationIsFenced(id)
pub fn generation_is_fenced(&self, id: &str) -> bool {
if id.is_empty() {
return false;
}
match self.store.get_snapshot(id, true) {
Ok(Some(s)) => s.get("generationCanceled") == Some(&Value::Bool(true)),
_ => false,
}
}
/// JS: generationPhaseAlreadyRecorded(id, phase)
pub fn generation_phase_already_recorded(&self, id: &str, phase: &str) -> bool {
match self.store.get_snapshot(id, true) {
Ok(Some(s)) => s
.get("generationTimings")
.and_then(|t| t.get(phase))
.map(|v| truthy(Some(v)))
.unwrap_or(false),
_ => false,
}
}
/// JS: recordGenerationCheckpoint(event)
pub fn record_generation_checkpoint(&mut self, event: &Map<String, Value>) {
let Some(id) = ev_str(event, "id")
.filter(|s| !s.is_empty())
.map(String::from)
else {
return;
};
if ev_str(event, "type") != Some("checkpoint") {
return;
}
if self.generation_is_fenced(&id) {
return;
}
let reason = ev_str(event, "reason").unwrap_or("");
if !VARIANT_PROGRESS_CHECKPOINT_REASONS.contains(&reason) {
return;
}
let arrived = crate::util::js_number(event.get("arrivedVariants")).unwrap_or(0.0);
let expected = crate::util::js_number(event.get("expectedVariants")).unwrap_or(0.0);
if arrived <= 0.0 || expected <= 0.0 {
return;
}
let preview_mode = match event.get("previewMode") {
Some(v) if truthy(Some(v)) => v.clone(),
_ => json!("source"),
};
let preview_file = match event.get("previewFile") {
Some(v) if truthy(Some(v)) => Some(v.clone()),
_ => event.get("file").filter(|v| truthy(Some(v))).cloned(),
};
if let Some(pf) = &preview_file {
let mut msg = Map::new();
msg.insert("type".into(), json!("variant_progress"));
msg.insert("id".into(), json!(id));
msg.insert("file".into(), pf.clone());
let source_file = match event.get("sourceFile") {
Some(v) if truthy(Some(v)) => Some(v.clone()),
_ => {
if preview_mode.as_str() == Some("source") {
Some(pf.clone())
} else {
None
}
}
};
if let Some(sf) = source_file {
msg.insert("sourceFile".into(), sf);
}
msg.insert("previewFile".into(), pf.clone());
msg.insert("previewMode".into(), preview_mode.clone());
msg.insert("arrivedVariants".into(), crate::util::js_num(arrived));
msg.insert("expectedVariants".into(), crate::util::js_num(expected));
msg.insert(
"publicationKind".into(),
match event.get("publicationKind") {
Some(v) if truthy(Some(v)) => v.clone(),
_ => json!("variants"),
},
);
self.broadcast(&Value::Object(msg));
}
let at = now_i64();
let details = |at: i64| -> Vec<(&'static str, Value)> {
vec![
("arrivedVariants", crate::util::js_num(arrived)),
("expectedVariants", crate::util::js_num(expected)),
(
"checkpointReason",
match event.get("reason") {
Some(v) if truthy(Some(v)) => v.clone(),
_ => Value::Null,
},
),
("at", json!(at)),
]
};
if !self.generation_phase_already_recorded(&id, "first_reviewable") {
self.record_agent_phase(&id, "first_reviewable", &details(at));
}
if arrived >= 2.0
&& expected >= 3.0
&& !self.generation_phase_already_recorded(&id, "second_reviewable")
{
self.record_agent_phase(&id, "second_reviewable", &details(at));
}
if arrived >= expected && !self.generation_phase_already_recorded(&id, "all_variants_ready")
{
self.record_agent_phase(&id, "all_variants_ready", &details(at));
}
}
/// JS: detectMissedGenerationCompletion(event)
pub fn detect_missed_generation_completion(&self, event: &Map<String, Value>) -> Option<Value> {
let id = ev_str(event, "id").filter(|s| !s.is_empty())?;
if ev_str(event, "type") != Some("checkpoint") {
return None;
}
if ev_str(event, "phase") != Some("generating") {
return None;
}
let arrived = crate::util::js_number(event.get("arrivedVariants")).unwrap_or(0.0);
let expected = crate::util::js_number(event.get("expectedVariants")).unwrap_or(0.0);
let behind = arrived <= 0.0 || (expected > 0.0 && arrived < expected);
if !behind {
return None;
}
let snapshot = self.store.get_snapshot(id, false).ok().flatten()?;
missed_completion_from_snapshot(&snapshot)
}
}
/// JS: missedCompletionFromSnapshot(snapshot)
pub fn missed_completion_from_snapshot(snapshot: &Map<String, Value>) -> Option<Value> {
let id = snapshot.get("id").filter(|v| truthy(Some(v)))?;
if !truthy(snapshot.get("generationCompletedAt")) {
return None;
}
if truthy(snapshot.get("generationCanceled")) {
return None;
}
let phase = snapshot.get("phase").and_then(|p| p.as_str()).unwrap_or("");
if GENERATION_FENCED_SESSION_PHASES.contains(&phase) {
return None;
}
let source_file = snapshot
.get("sourceFile")
.filter(|v| truthy(Some(v)))
.cloned();
let preview_file = snapshot
.get("previewFile")
.filter(|v| truthy(Some(v)))
.cloned();
let file = source_file.clone().or_else(|| preview_file.clone())?;
let mut m = Map::new();
m.insert("type".into(), json!("done"));
m.insert("id".into(), id.clone());
m.insert("file".into(), file);
if let Some(sf) = source_file {
m.insert("sourceFile".into(), sf);
}
if let Some(pf) = preview_file {
m.insert("previewFile".into(), pf);
}
if let Some(pm) = snapshot.get("previewMode").filter(|v| truthy(Some(v))) {
m.insert("previewMode".into(), pm.clone());
}
m.insert("redelivered".into(), json!(true));
Some(Value::Object(m))
}
/// JS: summarizeActiveSessionForClient(snapshot)
pub fn summarize_active_session_for_client(snapshot: &Map<String, Value>) -> Value {
let nn = |k: &str, d: Value| -> Value {
match snapshot.get(k) {
Some(v) if !v.is_null() => v.clone(),
_ => d,
}
};
let mut m = Map::new();
if let Some(id) = snapshot.get("id") {
m.insert("id".into(), id.clone());
}
if let Some(p) = snapshot.get("phase") {
m.insert("phase".into(), p.clone());
}
m.insert("pageUrl".into(), nn("pageUrl", Value::Null));
m.insert("sourceFile".into(), nn("sourceFile", Value::Null));
m.insert("previewFile".into(), nn("previewFile", Value::Null));
m.insert("previewMode".into(), nn("previewMode", Value::Null));
m.insert("expectedVariants".into(), nn("expectedVariants", json!(0)));
m.insert("arrivedVariants".into(), nn("arrivedVariants", json!(0)));
m.insert("visibleVariant".into(), nn("visibleVariant", Value::Null));
m.insert(
"checkpointRevision".into(),
nn("checkpointRevision", json!(0)),
);
let bcr = match snapshot.get("browserCheckpointRevision") {
Some(v) if !v.is_null() => v.clone(),
_ => nn("checkpointRevision", json!(0)),
};
m.insert("browserCheckpointRevision".into(), bcr);
m.insert(
"publicationCheckpointRevision".into(),
nn("publicationCheckpointRevision", json!(0)),
);
m.insert(
"paramValues".into(),
match snapshot.get("paramValues") {
Some(v) if truthy(Some(v)) => v.clone(),
_ => json!({}),
},
);
m.insert("generationPhase".into(), nn("generationPhase", Value::Null));
m.insert(
"generationCompletedAt".into(),
nn("generationCompletedAt", Value::Null),
);
m.insert(
"generationCanceled".into(),
json!(snapshot.get("generationCanceled") == Some(&Value::Bool(true))),
);
m.insert("cancelReason".into(), nn("cancelReason", Value::Null));
m.insert(
"mountedVariants".into(),
match snapshot.get("mountedVariants") {
Some(v @ Value::Array(_)) => v.clone(),
_ => json!([]),
},
);
m.insert(
"mountFailures".into(),
match snapshot.get("mountFailures") {
Some(v @ Value::Array(_)) => v.clone(),
_ => json!([]),
},
);
m.insert("renderState".into(), nn("renderState", Value::Null));
Value::Object(m)
}
/// JS: leaseEvent(entry, leaseMs) after the synchronous claim: scaffold a
/// generate event (preflight subprocess), re-stamp the lease, record
/// delivery. `entry_event` is the claimed entry's event; the queue entry (by
/// seq) is updated when still present.
pub fn lease_event(
shared: &Shared,
seq: i64,
entry_event: Map<String, Value>,
lease_ms: i64,
) -> Map<String, Value> {
let mut event = entry_event;
prepare_generate_event_for_lease(shared, seq, &mut event);
let mut st = lock(shared);
if !truthy(event.get("id")) {
st.pending_events.retain(|e| e.seq != seq);
return event;
}
if let Some(entry) = st.pending_events.iter_mut().find(|e| e.seq == seq) {
entry.lease_until = now_i64() + lease_ms;
}
// recordGenerateDelivery
if ev_str(&event, "type") == Some("generate") && !truthy(event.get("generationReadyAt")) {
let at = now_i64();
event.insert("generationReadyAt".into(), json!(at));
if let Some(entry) = st.pending_events.iter_mut().find(|e| e.seq == seq) {
entry.event = event.clone();
}
let _ = st.store.append_event(&Value::Object(event.clone()));
let id = ev_str(&event, "id").unwrap_or("").to_string();
st.record_agent_phase(&id, "generation_ready", &[("at", json!(at))]);
}
st.schedule_lease_flush();
st.broadcast_agent_polling_if_changed();
event
}
/// JS: prepareGenerateEventForLease(entry)
fn prepare_generate_event_for_lease(shared: &Shared, seq: i64, event: &mut Map<String, Value>) {
if ev_str(event, "type") != Some("generate") || truthy(event.get("scaffoldAttempted")) {
return;
}
let id = ev_str(event, "id").unwrap_or("").to_string();
let (cwd, env, cached) = {
let mut st = lock(shared);
st.record_agent_phase(&id, "picked_up", &[]);
st.record_agent_phase(&id, "scaffolding", &[]);
let sig = crate::preflight::target_signature(event);
let cached = st.source_resolution_cache.get(&sig).cloned();
(st.cwd.clone(), st.env.clone(), cached)
};
let result = run_generation_preflight(event, &cwd, &env, cached.as_deref());
let mut st = lock(shared);
match &result {
PreflightOutcome::Skipped => {}
PreflightOutcome::Ok {
signature,
resolved_source,
..
} => {
if let Some(src) = resolved_source {
st.source_resolution_cache
.insert(signature.clone(), src.clone());
}
}
PreflightOutcome::Err { signature, .. } => {
st.source_resolution_cache.remove(signature);
}
}
event.insert("scaffoldAttempted".into(), json!(true));
let (ok, duration, preview_mode) = match &result {
PreflightOutcome::Skipped => {
event.insert("scaffoldDurationMs".into(), Value::Null);
event.insert("scaffoldError".into(), json!("insufficient_locator"));
(false, Value::Null, json!("source"))
}
PreflightOutcome::Ok {
duration_ms,
scaffold,
..
} => {
let d = crate::util::js_num(*duration_ms);
event.insert("scaffoldDurationMs".into(), d.clone());
event.insert("scaffold".into(), scaffold.clone());
let pm = match scaffold.get("previewMode") {
Some(v) if truthy(Some(v)) => v.clone(),
_ => json!("source"),
};
(true, d, pm)
}
PreflightOutcome::Err {
duration_ms, error, ..
} => {
let d = crate::util::js_num(*duration_ms);
event.insert("scaffoldDurationMs".into(), d.clone());
event.insert("scaffoldError".into(), json!(error));
(false, d, json!("source"))
}
};
if let Some(entry) = st.pending_events.iter_mut().find(|e| e.seq == seq) {
entry.event = event.clone();
}
let _ = st.store.append_event(&Value::Object(event.clone()));
st.record_agent_phase(
&id,
if ok {
"source_ready"
} else {
"scaffold_fallback"
},
&[("durationMs", duration), ("previewMode", preview_mode)],
);
}
pub enum PreflightOutcome {
Skipped,
Ok {
signature: String,
duration_ms: f64,
scaffold: Value,
resolved_source: Option<String>,
},
Err {
signature: String,
duration_ms: f64,
error: String,
},
}
/// JS: runGenerationPreflight(event, { cwd, scriptsDir }): spawns this binary's
/// `live-wrap` / `live-insert --defer-source-write` with a 15 s timeout.
pub fn run_generation_preflight(
event: &Map<String, Value>,
cwd: &str,
env: &Env,
cached_file: Option<&str>,
) -> PreflightOutcome {
let Some(cmd) = build_generation_preflight(event, cached_file) else {
return PreflightOutcome::Skipped;
};
let started = Instant::now();
let exe = std::env::current_exe()
.map(|p| p.to_string_lossy().into_owned())
.unwrap_or_else(|_| "impeccable".to_string());
let mut child = match std::process::Command::new(&exe)
.arg(cmd.verb)
.args(&cmd.args)
.current_dir(cwd)
.env_clear()
.envs(env)
.stdin(std::process::Stdio::null())
.stdout(std::process::Stdio::piped())
.stderr(std::process::Stdio::piped())
.spawn()
{
Ok(c) => c,
Err(e) => {
return PreflightOutcome::Err {
signature: cmd.signature,
duration_ms: elapsed_ms(started),
error: compact_error("", Some(&e.to_string())),
};
}
};
let (out_tx, out_rx) = channel::<(Vec<u8>, Vec<u8>)>();
let mut stdout = child.stdout.take();
let mut stderr = child.stderr.take();
std::thread::spawn(move || {
use std::io::Read;
let mut o = Vec::new();
let mut e = Vec::new();
let et = std::thread::spawn(move || {
let mut e = Vec::new();
if let Some(s) = stderr.as_mut() {
let _ = s.read_to_end(&mut e);
}
e
});
if let Some(s) = stdout.as_mut() {
let _ = s.read_to_end(&mut o);
}
if let Ok(v) = et.join() {
e = v;
}
let _ = out_tx.send((o, e));
});
let deadline = Instant::now() + Duration::from_millis(PREFLIGHT_TIMEOUT_MS);
let mut timed_out = false;
let status = loop {
match child.try_wait() {
Ok(Some(s)) => break Some(s),
Ok(None) => {
if Instant::now() >= deadline {
let _ = child.kill();
let _ = child.wait();
timed_out = true;
break None;
}
std::thread::sleep(Duration::from_millis(5));
}
Err(_) => break None,
}
};
let (stdout, stderr) = out_rx.recv().unwrap_or_default();
let duration_ms = elapsed_ms(started);
let stdout = String::from_utf8_lossy(&stdout).into_owned();
let stderr = String::from_utf8_lossy(&stderr).into_owned();
let success = matches!(status, Some(s) if s.success());
if !success {
// JS: execFile rejects with `Command failed: <cmd> <args>` (plus the
// stderr, which compactError prefers when non-empty).
let _ = timed_out;
let message = format!(
"Command failed: {} {} {}",
exe,
cmd.verb,
cmd.args.join(" ")
);
return PreflightOutcome::Err {
signature: cmd.signature,
duration_ms,
error: compact_error(&stderr, Some(&message)),
};
}
let line = stdout
.trim()
.split('\n')
.filter(|l| !l.is_empty())
.last()
.map(String::from);
let Some(line) = line else {
return PreflightOutcome::Err {
signature: cmd.signature,
duration_ms,
error: compact_error("", Some("preflight returned no scaffold metadata")),
};
};
let scaffold: Value = match serde_json::from_str(&line) {
Ok(v) => v,
Err(_) => {
let msg = crate::json_error::json_parse_error(&line)
.unwrap_or_else(|| "Unexpected token".to_string());
return PreflightOutcome::Err {
signature: cmd.signature,
duration_ms,
error: compact_error("", Some(&msg)),
};
}
};
let resolved_source = scaffold
.get("sourceFile")
.and_then(|v| v.as_str())
.or_else(|| scaffold.get("file").and_then(|v| v.as_str()))
.map(String::from);
PreflightOutcome::Ok {
signature: cmd.signature,
duration_ms,
scaffold,
resolved_source,
}
}
fn elapsed_ms(started: Instant) -> f64 {
let d = started.elapsed();
// performance.now() resolution: fractional milliseconds.
(d.as_secs_f64() * 1000.0 * 1000.0).round() / 1000.0
}
/// JS: resolveProjectContext(): PRODUCT.md / DESIGN.md truth resolved per
/// request, roots manifest as fallback.
pub struct ProjectContext {
pub has_product: bool,
pub resolved_design_path: Option<String>,
pub context_dir: String,
pub design_context_dir: Option<String>,
}
pub fn resolve_project_context(
cwd: &str,
env: &Env,
roots: Option<&RootsManifest>,
) -> ProjectContext {
let ctx = impeccable_context::context::load_context(cwd, &TargetOptions::default(), env);
let design_path = match &ctx.design_path {
Some(p) => Some(jsp::resolve(cwd, &[p])),
None => roots
.and_then(|r| r.design_path.clone())
.filter(|p| crate::util::exists(p)),
};
let has_product = ctx.has_product
|| roots
.and_then(|r| r.product_path.as_deref())
.map(crate::util::exists)
.unwrap_or(false);
let context_dir = if !ctx.context_dir.is_empty() {
ctx.context_dir.clone()
} else {
roots
.and_then(|r| r.context_root.clone())
.unwrap_or_else(|| cwd.to_string())
};
let design_context_dir = ctx
.design_context_dir
.clone()
.or_else(|| design_path.as_deref().map(jsp::dirname));
ProjectContext {
has_product,
resolved_design_path: design_path,
context_dir,
design_context_dir,
}
}
/// JS: live-server.mjs#stripPollerOwnedEventFields (#488) — `_instructions`,
/// `_completionAck`, and `_acceptResult` are owned by the poller: a
/// page-supplied value must never suppress or impersonate the locally
/// generated next step.
pub fn strip_poller_owned_event_fields(event: &mut Map<String, Value>) {
for key in ["_instructions", "_completionAck", "_acceptResult"] {
event.remove(key);
}
}
/// `Number(process.env.X || '') || default`: a positive integer wins, anything
/// else falls back to the default.
fn env_positive_ms(env: &Env, key: &str) -> Option<u64> {
env.get(key)
.and_then(|v| v.trim().parse::<u64>().ok())
.filter(|v| *v > 0)
}
/// The verdict for a held target once every connected overlay declined. A
/// tab that could serve later (mid-session, an apply in flight) outranks a
/// page that simply lacks the element, so the agent retries instead of
/// giving up; only when no page can resolve the target does the resolution
/// verdict (`no_match`, `invalid_selector`, ...) come back.
pub fn agent_target_verdict_from_reports(pending: &AgentTargetPending) -> Value {
let busy = pending
.reports
.iter()
.find(|r| r.reason.as_str() != Some("no_match"))
.or_else(|| pending.reports.first());
if let Some(r) = busy.filter(|r| r.reason.as_str() != Some("no_match")) {
return json!({ "ok": false, "error": "busy", "state": r.state, "reason": r.reason });
}
if let Some(result) = pending.reports.iter().find_map(|r| r.result.as_ref()) {
let mut verdict = result.clone();
if let Some(obj) = verdict.as_object_mut() {
obj.insert("ok".into(), json!(false));
}
return verdict;
}
let first = pending.reports.first();
json!({
"ok": false,
"error": "busy",
"state": first.map(|r| r.state.clone()).unwrap_or(Value::Null),
"reason": first.map(|r| r.reason.clone()).unwrap_or(Value::Null),
})
}