agentix-cli 0.101.1 → 0.102.0

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:

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,17 @@ 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
+    }
+
     /// 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)?
 
@@ -569,7 +573,10 @@ final class Panel: NSPanel {
         }
         orb.show(state.orbPhase, tint: tint, colors: colors)
 
-        if state.isMeta {
+        if state.isMeta, case .caption(let words) = idle {
+            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 +590,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 +600,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/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() }