agentix-cli 0.101.2 → 0.102.1

package/apps/mac-voice/Sources/AgentXVoice/Character.swift

@@ -69,6 +69,11 @@ final class CharacterHost {
     private var carried: (from: NSPoint, rest: CGPoint)?
     /// What the answering agent sent it to show (#482), and its mark.
     private let guide = CharacterGuide()
+    /// Sent somewhere, and what its bubble says there (#562).
+    var sent: Bool { guide.showing != nil }
+    var caption: String? { guide.caption }
+    /// Told when it is sent somewhere, to its next stop or back.
+    var onGuide: (() -> Void)?
     /// A still picture: Reduce Motion, or "Animated orb" off.
     private var still: Bool { !animated || reduceMotion }
     /// The look is the character: whether it is on screen. Nil with the orb.
@@ -147,12 +152,13 @@ final class CharacterHost {
     }
 
     /// Go beside `rect` and mark it, or with nil go back to where it rests.
-    func guide(to rect: NSRect?, mark kind: GuideMath.Mark = .none) {
+    func guide(to rect: NSRect?, mark kind: GuideMath.Mark = .none, caption: String? = nil) {
         if shown, !hidden, carried == nil, let rect {
-            guide.show(rect, kind, color: view.stops[2], animated: !still)
+            guide.show(rect, kind, caption: caption, color: view.stops[2], animated: !still)
         } else {
             guide.end()
         }
+        onGuide?()
         redraw()
     }
 
@@ -192,7 +198,7 @@ final class CharacterHost {
         switch phase {
         case .began:
             let mouse = pointerSource()
-            if body.contains(mouse) { guide.end(glide: false); carried = (mouse, CGPoint(x: body.midX, y: rest.y)) }
+            if body.contains(mouse) { guide.end(glide: false); onGuide?(); carried = (mouse, CGPoint(x: body.midX, y: rest.y)) }
         case .moved:
             if carried != nil { tick() }
         case .ended:
@@ -271,7 +277,8 @@ final class CharacterHost {
         let head = min(max(top + 2 - PillPlacement.tail, Self.head), room)
         let moving = carried != nil || abs(sim.speed) > 8 || rest.y != spot.place.y || head > Self.head
         if still { motion = BubbleMotion() }
-        let small = still ? 0 : motion.step(now: now, moving: moving, holds: bubbleShows?() ?? false)
+        // A caption is to be read from the moment it is sent (#566).
+        let small = still ? 0 : motion.step(now: now, moving: moving, holds: guide.caption != nil || bubbleShows?() ?? false)
         let at = NSPoint(x: origin.x + Self.size.width / 2, y: origin.y + Self.ground + head)
         bubbleFrame = bubble?(at, visible, CGFloat(small))
         // Its tail, unless the bubble had to go beside it.

package/apps/mac-voice/Sources/AgentXVoice/Guide.swift

@@ -10,6 +10,9 @@ enum GuideClient {
         /// Nil: back to where it rests.
         let rect: Rect?
         let mark: String
+        /// What its bubble says at the stop (#562). Nil: no bubble there,
+        /// and a daemon too old to send one.
+        let text: String?
     }
 
     /// GET /voice/guide: the command after `seq`, as soon as there is
@@ -34,8 +37,8 @@ final class GuideWatcher {
     private var task: Task<Void, Never>?
     /// The character is on screen.
     var wanted: (() -> Bool)?
-    /// Show this, in AppKit coordinates, or go home.
-    var onCommand: ((NSRect?, GuideMath.Mark) -> Void)?
+    /// Show this, in AppKit coordinates, with this caption, or go home.
+    var onCommand: ((NSRect?, GuideMath.Mark, String?) -> Void)?
 
     /// (Re)start the wait. Called again when the character comes on screen
     /// or leaves it, so a wait already open is ended: cancelling it closes
@@ -53,7 +56,7 @@ final class GuideWatcher {
     private func turn() async {
         guard wanted?() == true, let command = await GuideClient.next(after: seq) else {
             // Hidden, or the daemon is gone: nothing is left on screen.
-            if away { away = false; onCommand?(nil, .none) }
+            if away { away = false; onCommand?(nil, .none, nil) }
             try? await Task.sleep(nanoseconds: 2_000_000_000)
             return
         }
@@ -65,7 +68,7 @@ final class GuideWatcher {
         }
         away = rect != nil
         Log.info("guide: \(rect.map { "to \(Int($0.minX)),\(Int($0.minY)) \(Int($0.width))x\(Int($0.height)) \(command.mark)" } ?? "home")")
-        onCommand?(rect, GuideMath.Mark(rawValue: command.mark) ?? .box)
+        onCommand?(rect, GuideMath.Mark(rawValue: command.mark) ?? .box, rect == nil ? nil : command.text)
     }
 }
 
@@ -74,13 +77,16 @@ final class GuideWatcher {
 @MainActor
 final class CharacterGuide {
     private(set) var showing: NSRect?
+    /// What its bubble says there (#562).
+    private(set) var caption: String?
     private let mark = GuideMark()
     /// On its way up or down, to what it shows or back; and the last frame.
     private var gliding = false
     private var ticked = 0.0
 
-    func show(_ rect: NSRect, _ kind: GuideMath.Mark, color: NSColor, animated: Bool) {
+    func show(_ rect: NSRect, _ kind: GuideMath.Mark, caption text: String?, color: NSColor, animated: Bool) {
         showing = rect
+        caption = text
         gliding = true
         mark.show(kind, around: rect, color: color, animated: animated)
     }
@@ -89,6 +95,7 @@ final class CharacterGuide {
     func end(glide: Bool = true) {
         gliding = glide && showing != nil
         showing = nil
+        caption = nil
         mark.hide()
     }
 

package/apps/mac-voice/Sources/AgentXVoice/GuideMath.swift

@@ -40,6 +40,24 @@ enum GuideMath {
         }
     }
 
+    /// What the bubble says while the assistant has nothing to say (#562).
+    enum Idle: Equatable { case hint, caption(String), nothing }
+
+    /// At a stop the bubble says the command's caption, and with none
+    /// there is no bubble; the idle hint is for where it rests, not for
+    /// a stop, the way there or a play. `away`: sent somewhere, or playing.
+    static func idle(caption: String?, away: Bool) -> Idle {
+        if let caption, !caption.isEmpty { return .caption(caption) }
+        return away ? .nothing : .hint
+    }
+
+    /// How wide the bubble is around a caption `words` wide (#566): its
+    /// words and the room at both ends of the row, no wider; never less
+    /// than holds its tail, nor more than the pill, where a long one scrolls.
+    static func bubbleWidth(words: CGFloat, full: CGFloat) -> CGFloat {
+        min(max(words.rounded(.up) + 52, 96), full)
+    }
+
     /// One frame of its way up or down to where it is sent: most of the
     /// way in a third of a second, and there once it is within a point.
     static func glide(_ y: CGFloat, toward goal: CGFloat, dt: Double) -> CGFloat {

package/apps/mac-voice/Sources/AgentXVoice/Panel.swift

@@ -130,6 +130,10 @@ final class Panel: NSPanel {
     var small: CGFloat = 0
     let dots = BubbleDots()
 
+    /// What the bubble says while the assistant is idle (#562): the hint,
+    /// the caption of what the character shows, or nothing while it is away.
+    private(set) var idle = GuideMath.Idle.hint
+
     /// Told of every state rendered, so the menu-bar icon can follow.
     var onRender: ((State) -> Void)?
 
@@ -358,7 +362,7 @@ final class Panel: NSPanel {
             clip.frame.size.width = clipWidth
             // Text that scrolled may fit now, and the other way round.
             marqueeText = ""
-            if !current.isMeta { setText(label.stringValue) }
+            if !current.isMeta || caption != nil { setText(label.stringValue) }
         }
         answer.frame = NSRect(x: 0, y: above ? h : 0, width: Self.expandedWidth, height: answerHeight)
         separator.frame = NSRect(x: 0, y: above ? h - 1 : answerHeight, width: bounds.width, height: 1)
@@ -424,7 +428,7 @@ final class Panel: NSPanel {
         // Growing or collapsing: it catches up on the next frame.
         guard placing == 0 else { return }
         shrink(expanded ? 0 : amount)
-        let shape = PillPlacement.shrunk(Self.size, small: small)
+        let shape = PillPlacement.shrunk(bubbleSize, small: small)
         let size = expanded ? frame.size : shape.size
         let to = NSRect(origin: PillPlacement.bubble(size: size, head: head, visible: visible, reach: shape.reach), size: size)
         guard to != frame else { return }
@@ -569,7 +573,13 @@ final class Panel: NSPanel {
         }
         orb.show(state.orbPhase, tint: tint, colors: colors)
 
-        if state.isMeta {
+        label.font = Brand.body(size: 12)
+        if let words = caption {
+            // In the answer's text size, to be read in a small video.
+            label.font = Brand.body()
+            label.textColor = .labelColor
+            setText(words)
+        } else if state.isMeta {
             stopMarquee()
             label.attributedStringValue = Brand.metaString(state.text, color: state.color)
             label.frame.origin.x = 0
@@ -583,7 +593,9 @@ final class Panel: NSPanel {
         // Grown into an answer, it stays until it collapses, idle or not;
         // so does a pill with agents still busy in its mini orbs.
         // Reduced, the orb is the assistant's place on screen: it stays, idle or not.
-        if dismissed || (state.isMeta && !alwaysVisible && !expanded && busyCount == 0 && !reduced) { hide() } else { show() }
+        // A caption shows like any words; away with none, the hint does not.
+        let quiet = state.isMeta && !expanded && busyCount == 0
+        if dismissed || (quiet && idle == .nothing) || (quiet && idle == .hint && !alwaysVisible && !reduced) { hide() } else { show() }
         // After showing or hiding: a still character draws its bubble's
         // tail only while the bubble is on screen.
         onLook?(state, tint, colors)
@@ -591,6 +603,14 @@ final class Panel: NSPanel {
         onRender?(state)
     }
 
+    /// The character was sent somewhere or back, or a play began or ended.
+    @MainActor
+    func setIdle(_ words: GuideMath.Idle) {
+        guard words != idle else { return }
+        idle = words
+        render(current)
+    }
+
     /// On screen with something to use: an answer, an error or the call
     /// buttons. The character does not play with the pointer then (#537).
     @MainActor

package/apps/mac-voice/Sources/AgentXVoice/PanelBubble.swift

@@ -15,12 +15,31 @@ extension Panel {
         small = amount
         row.alphaValue = max(1 - 2 * amount, 0)
         dots.alphaValue = max(2 * amount - 1, 0)
-        (contentView as? Surface)?.shape(size: amount > 0 ? PillPlacement.shrunk(Self.size, small: amount).size : nil)
+        (contentView as? Surface)?.shape(size: amount > 0 ? PillPlacement.shrunk(bubbleSize, small: amount).size : nil)
         invalidateShadow()
         // The row was not laid out while reduced, and the frame may already
         // be the full pill's: nothing else would lay it out again.
         if amount == 0, let content = contentView { layoutContent(content.bounds) }
     }
+
+    /// The caption the bubble says now (#566): at a stop it shows whatever
+    /// the assistant is doing; only an error or a call takes its place.
+    @MainActor
+    var caption: String? {
+        guard case .caption(let words) = idle else { return nil }
+        switch current {
+        case .error, .ringing, .onCall: return nil
+        default: return words
+        }
+    }
+
+    /// The bubble's size: with a caption, as wide as its words, no wider.
+    @MainActor
+    var bubbleSize: NSSize {
+        guard let caption else { return Self.size }
+        let words = (caption as NSString).size(withAttributes: [.font: Brand.body()]).width
+        return NSSize(width: GuideMath.bubbleWidth(words: words, full: Self.size.width), height: Self.size.height)
+    }
 }
 
 /// Three dots, in the middle of the bubble.

package/apps/mac-voice/Sources/AgentXVoice/main.swift

@@ -86,6 +86,8 @@ final class App: NSObject, NSApplicationDelegate {
     // An agent ringing the owner (#321).
     private let callWatcher = CallWatcher()
     private let guideWatcher = GuideWatcher()
+    /// A play runs, or its picture is being taken (#562).
+    private var playing = false
     private let ringer = Ringer()
     /// The call ringing on the pill now.
     private var ringingCall: IncomingCall?
@@ -236,6 +238,12 @@ final class App: NSObject, NSApplicationDelegate {
             && !busy && !recorder.isRecording && !play.running
     }
 
+    /// What the idle bubble says (#562): no hint at a guide stop, on the
+    /// way there or during a play; the stop's caption if it has one.
+    private func idleWords() {
+        panel.setIdle(GuideMath.idle(caption: character.caption, away: character.sent || playing))
+    }
+
     /// "Play on this page" (#505): one picture of the character's screen, the
     /// lines of text read on it, and the character plays on the picture,
     /// differently each time. The page itself is never touched.
@@ -252,12 +260,17 @@ final class App: NSObject, NSApplicationDelegate {
         }
         let stops = character.stops, size = screen.frame.size
         let start = PlayMath.Point(x: foot.x - screen.frame.minX, y: screen.frame.maxY - foot.y)
-        // Off its edge, so it is not in the picture twice.
+        // Off its edge, so it is not in the picture twice; its idle
+        // bubble too, which would stay in the picture all the play long.
         character.setShown(false)
+        playing = true
+        idleWords()
         Task { @MainActor in
             try? await Task.sleep(nanoseconds: 150_000_000)
             guard let picture = PlayRead.picture(of: screen), !busy, !recorder.isRecording else {
+                playing = false
                 character.setShown(settings?.general.look == "character")
+                idleWords()
                 return
             }
             play.start(picture: picture, on: screen, stops: stops, at: start)
@@ -403,7 +416,9 @@ final class App: NSObject, NSApplicationDelegate {
         statusMenu.onPlay = { [weak self] in self?.startPlay() }
         play.onEnd = { [weak self] in
             guard let self else { return }
+            self.playing = false
             self.character.setShown(self.settings?.general.look == "character")
+            self.idleWords()
         }
         panel.onShown = { [weak self] in self?.character.redraw() }
         panel.onDismiss = { [weak self] in self?.dismissPill() }
@@ -511,7 +526,8 @@ final class App: NSObject, NSApplicationDelegate {
         callWatcher.start()
         // The answering agent sends the character to something (#482).
         guideWatcher.wanted = { [weak self] in self?.character.onScreen == true }
-        guideWatcher.onCommand = { [weak self] rect, mark in self?.character.guide(to: rect, mark: mark) }
+        guideWatcher.onCommand = { [weak self] rect, mark, caption in self?.character.guide(to: rect, mark: mark, caption: caption) }
+        character.onGuide = { [weak self] in self?.idleWords() }
         guideWatcher.start()
         character.onScreenChanged = { [weak self] in self?.guideWatcher.start() }