Skip to main content

smix_authoring_propose/
lib.rs

1//! smix-authoring-propose — the fenced authoring-proposal tier.
2//!
3//! A failed flow run leaves a structured bundle on disk (`run-summary.json`,
4//! `*.fail.tree.json`, `failure.json`, screenshots). This crate turns that
5//! bundle, via a local `claude` CLI, into a [`Proposal`]: a machine-checkable
6//! list of edits over the real `smix_adapter_maestro::Step` /
7//! `smix_selector::Selector` vocabulary — never an invented predicate smix has
8//! no verb for.
9//!
10//! It is an authoring aid, fenced the same way as `smix-ai-tier`: deletable,
11//! opt-in, non-deterministic. Nothing that senses or acts depends on it.
12
13use std::path::Path;
14
15use serde::{Deserialize, Serialize};
16use smix_adapter_maestro::Step;
17use smix_error::{ExpectationFailure, FailureCode, FailureInit};
18use smix_selector::Selector;
19
20/// Re-exported so a CLI wire needs only this crate as a dependency, not
21/// `smix-ai-tier` directly — keeping the authoring-propose fence's allowlist
22/// to a single crate.
23pub use smix_ai_tier::AiTierConfig;
24
25/// A machine-checkable set of edits over a flow's `Vec<Step>`.
26#[derive(Clone, Debug, Serialize, Deserialize)]
27pub struct Proposal {
28    /// The proposed edits, in the order the model emitted them.
29    pub edits: Vec<ProposalEdit>,
30}
31
32/// One structured edit. Internally tagged on `op`; the tag value is the
33/// variant name lowerCamelCased (`replaceSelector`, `insertStep`,
34/// `reorderStep`, `replaceStep`), while the payload fields stay snake_case to
35/// mirror how `claude` naturally names them.
36#[derive(Clone, Debug, Serialize, Deserialize)]
37#[serde(tag = "op", rename_all = "camelCase")]
38pub enum ProposalEdit {
39    /// Swap the selector of a selector-bearing step.
40    ReplaceSelector {
41        /// Index of the step whose selector to replace.
42        step_index: usize,
43        /// The replacement selector.
44        new_selector: Selector,
45    },
46    /// Insert a new step before `before_index`. v1 policy restricts `step` to
47    /// a wait verb (`extendedWaitUntil` / `waitForAnimationToEnd`).
48    InsertStep {
49        /// Position to insert before (`0..=flow_len`).
50        before_index: usize,
51        /// The step to insert.
52        step: Step,
53    },
54    /// Move a step from one position to another.
55    ReorderStep {
56        /// Source index.
57        from_index: usize,
58        /// Destination index.
59        to_index: usize,
60    },
61    /// Replace a whole step (verb change, or the expressible subset of
62    /// assertion changes).
63    ReplaceStep {
64        /// Index of the step to replace.
65        step_index: usize,
66        /// The replacement step.
67        new_step: Step,
68    },
69}
70
71/// Why a [`Proposal`] failed [`Proposal::validate`].
72#[derive(Clone, Debug, PartialEq, Eq)]
73pub enum ProposalError {
74    /// An edit referenced a step index outside the flow.
75    IndexOutOfRange {
76        /// The offending index.
77        index: usize,
78        /// The flow length it was checked against.
79        flow_len: usize,
80    },
81    /// An `InsertStep` carried a step that is not a wait verb.
82    InsertNotWait {
83        /// The verb the insertion actually carried.
84        verb: &'static str,
85    },
86}
87
88impl Proposal {
89    /// Machine-check the v1 convergence policy: every index is in range
90    /// (`InsertStep.before_index` may equal `flow_len`), and every
91    /// `InsertStep` inserts a wait verb. Word-level vocabulary bounds on
92    /// `ReplaceSelector` / `ReplaceStep` are enforced by serde already — a
93    /// step or selector shape smix has no variant for never deserializes — so
94    /// `validate` adds no predicate allow-list. `ReorderStep` is structurally
95    /// well-formed once its indices are in range; whether a reorder is
96    /// *effective* is a C4 device concern, not a schema one.
97    pub fn validate(&self, flow_len: usize) -> Result<(), ProposalError> {
98        for edit in &self.edits {
99            match edit {
100                ProposalEdit::ReplaceSelector { step_index, .. }
101                | ProposalEdit::ReplaceStep { step_index, .. } => {
102                    check_in_range(*step_index, flow_len)?;
103                }
104                ProposalEdit::ReorderStep {
105                    from_index,
106                    to_index,
107                } => {
108                    check_in_range(*from_index, flow_len)?;
109                    check_in_range(*to_index, flow_len)?;
110                }
111                ProposalEdit::InsertStep { before_index, step } => {
112                    if *before_index > flow_len {
113                        return Err(ProposalError::IndexOutOfRange {
114                            index: *before_index,
115                            flow_len,
116                        });
117                    }
118                    match step {
119                        Step::ExtendedWaitUntil { .. } | Step::WaitForAnimationToEnd { .. } => {}
120                        other => {
121                            return Err(ProposalError::InsertNotWait {
122                                verb: step_verb(other),
123                            });
124                        }
125                    }
126                }
127            }
128        }
129        Ok(())
130    }
131}
132
133fn check_in_range(index: usize, flow_len: usize) -> Result<(), ProposalError> {
134    if index < flow_len {
135        Ok(())
136    } else {
137        Err(ProposalError::IndexOutOfRange { index, flow_len })
138    }
139}
140
141/// Pull a [`Proposal`] out of a model reply, tolerating prose around the JSON
142/// object — the same forgiving extraction `smix-ai-tier` uses for verdicts.
143pub fn parse_proposal_reply(reply: &str) -> Option<Proposal> {
144    smix_ai_tier::parse_json_object::<Proposal>(reply)
145}
146
147/// Ask a local `claude` to read a failed flow's bundle and propose edits.
148///
149/// The prompt points `claude` (with `--tools Read`) at the original flow and
150/// the on-disk bundle — `run-summary.json`, `failure.json`, any
151/// `*.fail.tree.json`, any screenshots — and asks for one JSON object of
152/// edits. A reply that is not a well-shaped [`Proposal`] is a driver error,
153/// not an empty proposal: "the model answered but not in the shape asked for"
154/// is a different claim from "there is nothing to improve".
155///
156/// The only external call is the local `claude` CLI (via [`smix_ai_tier::ask`]);
157/// no network Claude API path is touched.
158pub async fn propose_from_bundle(
159    flow_path: &Path,
160    bundle_dir: &Path,
161    cfg: &AiTierConfig,
162) -> Result<Proposal, ExpectationFailure> {
163    let prompt = format!(
164        "A smix test flow failed. Read the original flow at {flow} and the run \
165         artifacts in {bundle}: run-summary.json (per-step verdicts), \
166         failure.json (the structured failure with selector, suggestions, and \
167         visible elements), any *.fail.tree.json (the accessibility tree at the \
168         failing step), and any .png screenshots.\n\n\
169         Propose the edits that would make the flow pass. Reply with one JSON \
170         object and nothing else:\n\
171         {{\"edits\": [ <edit>, ... ]}}\n\n\
172         The single most reliable repair signal is the `suggestions` array in \
173         failure.json (the driver's \"Did you mean ...?\" list for a selector \
174         that matched nothing); prefer swapping the failing selector to a \
175         suggested one. `*.fail.tree.json` and .png may be absent — ignore them \
176         if missing rather than treating their absence as an error.\n\n\
177         Each <edit> is exactly one of:\n\
178         {{\"op\": \"replaceSelector\", \"step_index\": <n>, \"new_selector\": <selector>}}\n\
179         {{\"op\": \"insertStep\", \"before_index\": <n>, \"step\": <step>}}   (step must be extendedWaitUntil or waitForAnimationToEnd)\n\
180         {{\"op\": \"reorderStep\", \"from_index\": <n>, \"to_index\": <n>}}\n\
181         {{\"op\": \"replaceStep\", \"step_index\": <n>, \"new_step\": <step>}}\n\n\
182         Every index (`step_index`, `before_index`, `from_index`, `to_index`) \
183         is 0-based into the flow's step list: the first step is 0. Do not use \
184         the 1-based `n` from run-summary.json's `steps[].n`.\n\n\
185         A <selector> is a maestro selector object, e.g. {{\"id\": \"submit-btn\"}} \
186         or {{\"text\": \"Login\"}}. A <step> is a maestro step object, e.g. \
187         {{\"tapOn\": {{\"selector\": {{\"id\": \"submit-btn\"}}}}}} or \
188         {{\"extendedWaitUntil\": {{\"selector\": {{\"id\": \"spinner\"}}, \"timeout_ms\": 5000, \"expect_visible\": false}}}}.",
189        flow = flow_path.display(),
190        bundle = bundle_dir.display(),
191    );
192
193    // The text-only form: this tier reads the failure bundle itself and
194    // puts the material in the words, so nothing has to be opened on the
195    // other side.
196    let reply = smix_ai_tier::ask(prompt, cfg).await?;
197
198    parse_proposal_reply(&reply).ok_or_else(|| {
199        driver_error(
200            format!(
201                "authoring-propose: no proposal in the reply — wanted a JSON object, got: {}",
202                reply.trim()
203            ),
204            Some(
205                "the model answered but not in the shape asked for; this is not \
206                 an empty proposal"
207                    .into(),
208            ),
209        )
210    })
211}
212
213/// Why [`apply`] could not turn a [`Proposal`] into an amended flow.
214#[derive(Clone, Debug, PartialEq, Eq)]
215pub enum ApplyError {
216    /// The proposal failed [`Proposal::validate`] (index out of range, or
217    /// an `InsertStep` carrying a non-wait verb).
218    Invalid(ProposalError),
219    /// A `ReplaceSelector` targeted a step that carries no selector.
220    /// Refusing beats a silent no-op: the model asked to change a selector
221    /// on a step that has none, which is a malformed proposal, not a
222    /// change to drop on the floor.
223    NoSelector {
224        /// The targeted step index.
225        step_index: usize,
226        /// The verb of the step that has no selector.
227        verb: &'static str,
228    },
229}
230
231impl std::fmt::Display for ApplyError {
232    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
233        match self {
234            ApplyError::Invalid(e) => write!(f, "proposal failed validation: {e:?}"),
235            ApplyError::NoSelector { step_index, verb } => write!(
236                f,
237                "replaceSelector at step {step_index} targets `{verb}`, which has no selector"
238            ),
239        }
240    }
241}
242
243impl std::error::Error for ApplyError {}
244
245/// Validate a [`Proposal`] then apply its edits to a copy of `steps`,
246/// returning the amended flow. Validation runs first (index bounds +
247/// insert-wait policy); a failure propagates as [`ApplyError::Invalid`]
248/// rather than a partial mutation. Edits apply in the order the model
249/// emitted them.
250///
251/// Device-free: a pure `Vec<Step>` transform, no emit / parse / claude /
252/// sim involved.
253///
254/// # Errors
255///
256/// [`ApplyError::Invalid`] when [`Proposal::validate`] rejects the
257/// proposal; [`ApplyError::NoSelector`] when a `ReplaceSelector` targets a
258/// step with no selector field.
259pub fn apply(proposal: &Proposal, steps: &[Step]) -> Result<Vec<Step>, ApplyError> {
260    proposal
261        .validate(steps.len())
262        .map_err(ApplyError::Invalid)?;
263    let mut out = steps.to_vec();
264    for edit in &proposal.edits {
265        match edit {
266            ProposalEdit::ReplaceSelector {
267                step_index,
268                new_selector,
269            } => {
270                set_step_selector(&mut out[*step_index], new_selector.clone()).map_err(|verb| {
271                    ApplyError::NoSelector {
272                        step_index: *step_index,
273                        verb,
274                    }
275                })?;
276            }
277            ProposalEdit::InsertStep { before_index, step } => {
278                out.insert(*before_index, step.clone());
279            }
280            ProposalEdit::ReorderStep {
281                from_index,
282                to_index,
283            } => {
284                let s = out.remove(*from_index);
285                out.insert(*to_index, s);
286            }
287            ProposalEdit::ReplaceStep {
288                step_index,
289                new_step,
290            } => {
291                out[*step_index] = new_step.clone();
292            }
293        }
294    }
295    Ok(out)
296}
297
298fn set_step_selector(step: &mut Step, new_selector: Selector) -> Result<(), &'static str> {
299    match step {
300        Step::TapOn { selector, .. }
301        | Step::ExtendedWaitUntil { selector, .. }
302        | Step::AssertVisible { selector }
303        | Step::AssertNotVisible { selector }
304        | Step::InputTextInto { selector, .. }
305        | Step::ScrollUntilVisible { selector, .. }
306        | Step::CopyTextFrom { selector }
307        | Step::DoubleTapOn { selector }
308        | Step::RepeatTap { selector, .. }
309        | Step::LongPressOn { selector, .. } => {
310            *selector = new_selector;
311            Ok(())
312        }
313        other => Err(step_verb(other)),
314    }
315}
316
317fn driver_error(message: String, hint: Option<String>) -> ExpectationFailure {
318    ExpectationFailure::new(FailureInit {
319        code: Some(FailureCode::DriverError),
320        message,
321        hint,
322        ..Default::default()
323    })
324}
325
326/// Why [`propose_and_amend`] could not turn a failed flow + its bundle into an
327/// amended flow yaml. Each arm names the stage that failed; nothing is
328/// swallowed and no stage falls back to an empty amend.
329#[derive(Debug)]
330pub enum AmendError {
331    /// The flow file could not be read.
332    ReadFlow(std::io::Error),
333    /// The flow yaml did not parse.
334    ParseFlow(String),
335    /// The local `claude` step failed (CLI error, or a reply that was not a
336    /// well-shaped [`Proposal`]). Boxed: an `ExpectationFailure` is ~10× the
337    /// size of the other arms, so an unboxed variant bloats every `AmendError`.
338    Propose(Box<ExpectationFailure>),
339    /// The proposal could not be applied to the flow's steps.
340    Apply(ApplyError),
341    /// The amended steps could not be emitted back to maestro yaml.
342    Emit(smix_adapter_maestro::EmitError),
343}
344
345/// Glue the C2/C3 pieces into one device-free primitive: read `flow_path`,
346/// parse it, ask a local `claude` to propose edits from the on-disk `bundle_dir`,
347/// apply them, and emit the amended flow as maestro yaml.
348///
349/// The only external call is the local `claude` CLI (through
350/// [`propose_from_bundle`]); no network Claude API path is touched. Every stage
351/// error maps to its own [`AmendError`] arm — a failing claude surfaces, it
352/// never collapses to an empty amend.
353pub async fn propose_and_amend(
354    flow_path: &Path,
355    bundle_dir: &Path,
356    cfg: &AiTierConfig,
357) -> Result<String, AmendError> {
358    let yaml = std::fs::read_to_string(flow_path).map_err(AmendError::ReadFlow)?;
359    let flow = smix_adapter_maestro::parse_flow_yaml(&yaml)
360        .map_err(|e| AmendError::ParseFlow(e.to_string()))?;
361
362    let proposal = propose_from_bundle(flow_path, bundle_dir, cfg)
363        .await
364        .map_err(|e| AmendError::Propose(Box::new(e)))?;
365
366    let amended = apply(&proposal, &flow.steps).map_err(AmendError::Apply)?;
367    smix_adapter_maestro::emit_flow_yaml(&amended, &flow.app_id).map_err(AmendError::Emit)
368}
369
370fn step_verb(step: &Step) -> &'static str {
371    match step {
372        Step::TapOn { .. } => "tapOn",
373        Step::TapAtPoint { .. } => "tapAtPoint",
374        Step::WebViewEval { .. } => "webViewEval",
375        Step::WaitForAnimationToEnd { .. } => "waitForAnimationToEnd",
376        Step::ExtendedWaitUntil { .. } => "extendedWaitUntil",
377        Step::AssertVisible { .. } => "assertVisible",
378        Step::InputText(_) => "inputText",
379        Step::InputTextInto { .. } => "inputTextInto",
380        Step::PressKey(_) => "pressKey",
381        Step::Back(_) => "back",
382        Step::RunFlow(_) => "runFlow",
383        Step::RunFlowConditional { .. } => "runFlowConditional",
384        Step::RunFlowInline { .. } => "runFlowInline",
385        Step::ScrollUntilVisible { .. } => "scrollUntilVisible",
386        Step::EraseText(_) => "eraseText",
387        Step::Swipe { .. } => "swipe",
388        Step::LaunchApp { .. } => "launchApp",
389        _ => "step",
390    }
391}