forge_workspace/

conversation_turns.rs

//! Where a conversation's turns open, in the shape the fold reads them.
//!
//! **One rule, two readers.** A page is cut on the fold's turn boundaries, and
//! so is the window a session keeps its conversation in: a window that starts
//! part-way through a turn serves its first turn with the head missing. The
//! fold lives above this crate (`forge_server::transcript`), so the row
//! predicates it reads live here and both readers share the one copy.
//!
//! **This answers no more than the fold would.** Every frame [`TurnScan`]
//! names is one the fold opens a turn at; it names none the fold would not.
//! Three shapes it cannot read the way the fold does are answered the safe way
//! (no turn), so what they cost is a head the window cannot start on, never a
//! cut inside a turn.
//!
//! A queued prompt opens a turn in the fold, and the scan answers none for it.
//! That miss is not only the prompt: the fold's turn opens there and resets the
//! state the next turn opens under, so a frame the fold then draws as a head of
//! its own - the continuation a compaction leaves - is left alone here too.
//! `opens_for_debt` answers for it, because the counter debt read wants the
//! fold's openings rather than the cut's: a missed one carries the previous
//! turn's counters into the newest.
//!
//! And a row opening with a bracket is read as an envelope, because every
//! envelope this workspace writes opens with one and the parser that tells an
//! envelope from the reader's own words lives above this crate. That is broader
//! than the envelopes: a reader's own `[note] ...` row, and a bracket-led
//! notice the parser rejects, are heads here that this leaves alone. The shapes
//! read here are exempt from that, so an image note the fold opens a turn at is
//! named. **A delivery's envelope row opens a turn in the fold unless the CLI
//! pressed it into a running turn, and this side answers none for it** - the
//! accepted cost a queued prompt pays above: a head the window cannot start
//! on, never a cut inside a turn. The debt read answers for it too, on the
//! row's bracket alone ([`is_envelope_row`]).
//!
//! And a forge-minted row arriving at an open call is a delivery the CLI
//! pressed into the running turn - the fold keeps it there and opens no turn
//! (#2379). That answer needs the whole list (the fold declines only where the
//! call's result really comes); a stream cannot read it, so this side answers
//! no turn for the row, and for a call whose result never arrives it keeps
//! answering that way - heads the window cannot start on.

use forge_primitives::messages::names_a_dispatch;
use forge_primitives::{ContentBlock, Message};

/// Where the fold opens a conversation turn, walked frame by frame.
#[derive(Default)]
pub struct TurnScan {
    /// The skills the open turn holds a call for, oldest first: a skill's body
    /// belongs in the turn whose call loaded it.
    skills: Vec<String>,
    /// Whether a compaction boundary sits in the open turn. The continuation
    /// prompt that follows belongs beside it, so it opens no turn of its own
    /// while this holds.
    boundary: bool,
    /// Whether the open turn has taken a tool call. The harness's line about
    /// an image it read arrives right behind the call that read it, so it
    /// joins that turn rather than opening one.
    calls: bool,
    /// The open turn's calls still waiting on their results, oldest first. A
    /// forge-minted row arriving at one is a delivery pressed into the running
    /// turn: the fold keeps it there, so no turn opens here either.
    ///
    /// The fold answers that row too, and it can answer it more sharply - it
    /// reads the whole list and declines only where the call's result really
    /// comes. This side reads a stream, so a call whose result never arrives
    /// (the restart shape, #1836) is declined here and opened there: a head
    /// the window cannot start on, never a cut inside a turn.
    open: Vec<String>,
}

impl TurnScan {
    /// Whether the fold opens a conversation turn at this frame, under the
    /// state the frames before it left.
    pub fn opens(&mut self, message: &Message) -> bool {
        // A sub-agent's frames are the SUBAGENTS surface's, not the chat's.
        if is_dispatched(message) {
            return false;
        }
        match message {
            Message::CompactBoundary { .. } => {
                self.boundary = true;
                false
            }
            // A call's own row opens no turn, but a `Skill` call is what makes
            // the body behind it belong to this turn rather than opening one.
            Message::Assistant { message: envelope, .. } => {
                self.calls_in(&envelope.content);
                false
            }
            Message::User { message: envelope, uuid, .. } => {
                let mut opens = false;
                for block in &envelope.content {
                    match block {
                        ContentBlock::Text { text, .. } => {
                            if claims_skill_call(&mut self.skills, text) {
                                continue;
                            }
                            if self.boundary && is_continuation(text) {
                                self.boundary = false;
                                continue;
                            }
                            if self.calls && is_image_note(text) {
                                continue;
                            }
                            if is_task_notice(text) {
                                continue;
                            }
                            // The bracket fallback below would catch the
                            // interrupt marker only when it opens the string,
                            // and the fold's own read trims first - so a
                            // whitespace-led marker would open a turn here and
                            // none there, and the window could cut inside a
                            // turn. Read by the predicate, in step with the
                            // fold.
                            if is_interrupt_marker(text) {
                                continue;
                            }
                            // Every envelope this workspace writes opens with a
                            // bracket, and the parser that tells one from the
                            // reader's own words lives above this crate - so a
                            // bracket-led row is left alone unless it is a
                            // shape read here.
                            if text.starts_with('[') && !is_image_note(text) {
                                continue;
                            }
                            // **A forge-minted row at an open call is a
                            // delivery pressed into the running turn**: the
                            // fold keeps it there (#2379), and a head named
                            // here would start the window inside that turn.
                            // The fold's own bound - the result really coming
                            // - needs the whole list; a stream cannot read it,
                            // so this side answers no turn and the window
                            // loses only a head.
                            if forge_minted(uuid.as_deref()) && !self.open.is_empty() {
                                continue;
                            }
                            self.skills.clear();
                            self.boundary = false;
                            self.calls = false;
                            self.open.clear();
                            opens = true;
                        }
                        other => self.calls_in(std::slice::from_ref(other)),
                    }
                }
                opens
            }
            _ => false,
        }
    }

    /// The blocks that move the state the next turn opens under rather than
    /// opening one: a call, the result that answers one, and a `Skill` call's
    /// own name for what it loads.
    fn calls_in(&mut self, content: &[ContentBlock]) {
        for block in content {
            if let ContentBlock::ToolResult { tool_use_id, .. }
            | ContentBlock::ServerToolResult { tool_use_id, .. } = block
            {
                self.open.retain(|open| open != tool_use_id);
                continue;
            }
            if let ContentBlock::ToolUse { id, name, input, .. }
            | ContentBlock::ServerToolUse { id, name, input, .. } = block
            {
                self.calls = true;
                self.open.push(id.clone());
                if let Some(want) = input
                    .get("skill")
                    .and_then(serde_json::Value::as_str)
                    .filter(|_| name.eq_ignore_ascii_case("skill"))
                {
                    self.skills.push(want.to_owned());
                }
            }
        }
    }
}

/// Whether a user row's id says forge minted it: a reader's own send
/// (`forge_prompt_*`) or the machinery's dispatch (`forge_nudge_*`), the two
/// namespaces `forge_sdk::request_id` mints.
///
/// **The id is the one fact about the sender the CLI carries into the
/// transcript**, so it is what tells a row the CLI is pressing into a running
/// turn from a row that opens one - an id minted elsewhere is not this
/// workspace's row.
pub fn forge_minted(uuid: Option<&str>) -> bool {
    uuid.is_some_and(|id| id.starts_with("forge_prompt_") || id.starts_with("forge_nudge_"))
}

/// Whether a frame opens a turn for a reader that attributes counters to the
/// newest turn: the scan's own openings plus the two shapes the fold opens at
/// and the window cut deliberately cannot name - a queued prompt and a
/// delivery's envelope row.
///
/// **The cut's under-approximation is safe; the debt's is not.** A cut the
/// scan cannot start on leaves a turn's head in place, while a debt
/// attributed to the wrong turn adds another turn's counters to the figure.
pub fn opens_for_debt(scan: &mut TurnScan, message: &Message) -> bool {
    let named = scan.opens(message);
    named || is_queued_prompt(message) || is_envelope_row(message)
}

/// Whether a frame is the CLI's queued prompt, which the fold opens a turn at.
pub fn is_queued_prompt(message: &Message) -> bool {
    let Message::User { message, .. } = message else {
        return false;
    };
    message.content.iter().any(|block| matches!(block, ContentBlock::QueuedCommand { .. }))
}

/// Whether a frame is a bracket-led row: the shape every envelope this
/// workspace injects opens with - a delivery, a peer wrapper, a failure.
///
/// **The prefix alone, on purpose.** The parser that tells a real envelope
/// from the reader's own `[note]` row lives above this crate, and the two
/// readers want opposite answers about it: the cut must never start on a frame
/// the fold opens nothing at, while the debt must not carry a previous turn's
/// counters into the newest. So the cut leaves every bracket-led row alone and
/// the debt counts every one as an opening - the debt's error is then a figure
/// short of counters rather than one holding another turn's.
pub fn is_envelope_row(message: &Message) -> bool {
    let Message::User { message, .. } = message else {
        return false;
    };
    message
        .content
        .iter()
        .any(|block| matches!(block, ContentBlock::Text { text, .. } if text.starts_with('[')))
}

/// A frame a sub-agent produced. What it narrates and calls belongs to the
/// SUBAGENTS surface, never to the session's own conversation.
pub fn is_dispatched(message: &Message) -> bool {
    let (Message::Assistant { parent_tool_use_id: parent, .. }
    | Message::User { parent_tool_use_id: parent, .. }
    | Message::StopHookSummary { parent_tool_use_id: parent, .. }) = message
    else {
        return false;
    };
    names_a_dispatch(parent.as_deref())
}

/// Whether a turn's text is the harness's own task notice rather than anything
/// a person said: the marker the CLI writes at the head of the XML.
///
/// Two carriers hold it - the `attachment` row the scan hoists into a
/// `queued_command` block, and a `user` row whose content string is the XML -
/// and the fold reads the marker out of both, so a third shape would arrive
/// here and not elsewhere.
pub fn is_task_notice(text: &str) -> bool {
    text.trim_start().starts_with("<task-notification>")
}

/// Whether `text` is the harness's own line about an image it just read.
///
/// The CLI sends it as the reader's own row right after the result that
/// carried the image; the client fold hangs it on the call that read the
/// picture (`imageNoteOf` in its `units.ts`), so it belongs in that call's
/// turn rather than in one of its own.
pub fn is_image_note(text: &str) -> bool {
    text.trim().starts_with("[Image: original ")
}

/// Whether `text` is the CLI's interrupt marker: the row it writes when the
/// reader's own interrupt ends a turn.
///
/// A `user` row, and not one that opens a turn (#1323): it arrives INSIDE
/// the turn it ended - the in-flight call, then this, then the failing
/// `Result` - so a turn opened for it separates the call from the report
/// and failure line that answer it. Both folds read it as a plain row of
/// the open turn (the client mirror is `isInterruptMarker` in its
/// `conversation.ts`).
pub fn is_interrupt_marker(text: &str) -> bool {
    let held = text.trim_start();
    held.starts_with("[Request interrupted by user") && held.contains(']')
}

/// Whether `text` is the continuation prompt a compaction leaves behind.
///
/// The CLI sends it as the reader's own user row right after the boundary
/// frame, and it is the compaction's own account of what was cut. The client
/// fold hangs it on the boundary's row (`attachContinuation` in its
/// `units.ts`), and the two reads must agree.
pub fn is_continuation(text: &str) -> bool {
    text.starts_with("This session is being continued from a previous conversation")
}

/// The skill a body's own frame names, off its first line's directory.
///
/// The CLI injects a skill's body as a user row whose first line names the
/// skill's directory and whose remainder is the skill's markdown. The name is
/// the path's last segment that is not a version, so a plugin-cached skill
/// (`.../ui-ux-pro-max/2.13.0`) is named as its directory names it - the same
/// reading the web client's fold makes (`skillBody` in its `units.ts`).
pub fn skill_body_name(text: &str) -> Option<&str> {
    let lead = text.split('\n').next()?;
    if let Some(path) = lead.strip_prefix("Base directory for this skill:") {
        let path = path.trim();
        return path
            .split('/')
            .rev()
            .find(|part| part.chars().next().is_some_and(|c| !c.is_ascii_digit()));
    }
    // The carrier a tool-invoked skill uses: the skill's own markdown, opening
    // on its title heading (`# PR Review Loop` for `pr-review-loop`) with no
    // plumbing line. The heading is the whole of what names it, so that is the
    // name - normalized by `names_skill`, the same match the client makes.
    let trimmed = lead.trim();
    let title = trimmed.trim_start_matches('#');
    if title.len() == trimmed.len() || !title.starts_with(' ') {
        return None;
    }
    let title = title.trim();
    (!title.is_empty()).then_some(title)
}

/// Whether `text` is the body of a skill the open turn holds a call for,
/// consuming that claim.
///
/// A body belongs in the turn whose call loaded it: it is the same telling the
/// call's row already carries, and a turn of its own draws it a second time
/// under the reader's name. The claim is consumed so a later body for the same
/// skill lands on the call after it, and a body no call holds opens a turn as
/// it did before - nothing may be dropped.
pub fn claims_skill_call(turn_skills: &mut Vec<String>, text: &str) -> bool {
    let Some(name) = skill_body_name(text) else {
        return false;
    };
    let Some(at) = turn_skills.iter().position(|want| names_skill(want, name)) else {
        return false;
    };
    turn_skills.remove(at);
    true
}

/// Whether a `Skill` call's own input names the skill a body's path ended in.
///
/// The spellings differ two ways: a plugin skill is `ui-ux-pro-max:ui-ux-pro-max`
/// where the path ends `ui-ux-pro-max`, and a tool-invoked body's heading is
/// `PR Review Loop` where the call says `pr-review-loop`. The client fold
/// matches the same way (`namesSkill` in its `units.ts`); the two must agree,
/// or the same frame lands in one view and not the other.
pub fn names_skill(want: &str, name: &str) -> bool {
    if want == name || want.ends_with(&format!(":{name}")) || want.starts_with(&format!("{name}:"))
    {
        return true;
    }
    let held = normalized_skill(want);
    let wanted = normalized_skill(name);
    held == wanted || held.contains(&wanted) || wanted.contains(&held)
}

/// A skill name as its words, so `pr-review-loop` and `PR Review Loop` agree.
pub fn normalized_skill(name: &str) -> String {
    name.to_lowercase()
        .chars()
        .map(|c| if c == '-' || c == '_' || c == ':' { ' ' } else { c })
        .collect::<String>()
        .split_whitespace()
        .collect::<Vec<_>>()
        .join(" ")
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A delivery's envelope row answers the two readers differently: the cut
    /// leaves it alone, and the debt counts it as an opening.
    ///
    /// The parser that tells a real envelope from the reader's own bracket row
    /// lives above this crate, so the debt reads the prefix - broader than the
    /// fold opens at, which is the safe side for a counter figure: a figure
    /// short of counters is a smaller error than one carrying the previous
    /// turn's.
    #[test]
    fn a_delivery_row_opens_for_the_debt_and_not_for_the_cut() {
        let row: Message = serde_json::from_value(serde_json::json!({
            "type": "user",
            "uuid": "u1",
            "message": {
                "role": "user",
                "content": "[Gotify - app 'ci', priority 9]\n\nbuild failed",
            },
            "session_id": "s",
        }))
        .expect("a user frame");

        assert!(!TurnScan::default().opens(&row), "the cut cannot name a bracket-led row");
        assert!(
            opens_for_debt(&mut TurnScan::default(), &row),
            "and the debt read must count the turn it opens",
        );
    }
}