Run AI spotlight through real agent runtime

Author: KSemenenko

AGENTS.md

@@ -103,6 +103,7 @@ Rule format:
 - TPS pronunciation and phonetic cue examples must use realistic pronunciation notation with IPA-style symbols and stress marks, not placeholder labels such as `GUIDE` or `IPA`.
 - TPS cue matrix focus words must name the cue being demonstrated when possible, for example `[sad]sad[/sad]` instead of styling a generic word such as `calibration`, so each screenshot is understandable on its own.
 - TPS articulation visuals must follow music-reading metaphors: `legato` should read like one curved slur/ligature mark spanning the entire cue word or grouped phrase, not a wavy spelling-style underline or separate per-word marks; `staccato` should read as dots.
+- TPS legato and other curved reader marks must render as smooth vector-quality strokes at README screenshot scale; do not use CSS gradients or raster tricks that create jagged, stair-stepped, or pixelated curves.
 - TPS crescendo, stress, legato, pronunciation, phonetic, emphasis, and other scope-based cue treatments must cover the full cue word or phrase scope when the tag applies to a whole word or phrase; partial-letter or single-glyph decoration is a regression unless the TPS semantics explicitly target only that glyph.
 - TPS editorial cues must remain visually distinct: `[emphasis]`, Markdown `**bold**`, Markdown `*italic*`, and `[highlight]` need separate reader treatments instead of collapsing into the same underline or generic emphasis style.
 - TPS cue matrix reviews must explicitly compare similar treatments side by side and reject identical-looking cue families; screenshots are not acceptable until a reader can tell the intended semantics apart at normal README scale.
@@ -174,9 +175,11 @@ Rule format:
 - Shared top-bar chrome must use one consistent navigation contract across routed screens: the app brand/icon acts as Home, the Back control uses real browser/in-app history when available, and responsive phone/tablet layouts must keep those actions reachable without overlapping or clipping.
 - The PrompterOne AI assistant belongs in global shell/header chrome, must be available on every routed screen through a spotlight-style surface and hotkey, and must not remain an editor-only action.
 - The AI spotlight is a command/search palette plus agent chat/execution surface, not a planning screen: it should suggest route-aware commands and navigation targets while typing, send the entered prompt to the agent on submit, show execution progress only as live process/status feedback, and use a macOS Spotlight-style overlay where the underlying route remains visible with only a very light dim and no dark blurred full-page backdrop.
+- AI spotlight must not fake agent execution: when a provider is configured, submitting a prompt must invoke a real Microsoft Agent Framework agent with the user prompt, route/editor context, and MCP-style tool catalog; when no provider is configured, the UI must clearly report that AI is unavailable instead of showing a pretend working state.
 - The AI spotlight prompt input must receive focus immediately when the spotlight opens so users can start typing without an extra click.
 - Script graph views must prioritize a readable writer knowledge map over decorative circular placement or raw TPS/source dumps: highlight the main/root document node, group meaningful document structure, ideas, people, themes, story references, and relationships by graph value/kind, expose node and edge hover tooltips with source detail, provide zoom/fit/layout controls, avoid noisy duplicated node-list strips under the graph, and never present source lines, WPM/pace, timing, cue, archetype, or raw TPS attribute values as primary graph nodes or primary edge labels. Graph viewing must support both a full graph-only mode and a split source/graph mode with a user-draggable divider that resizes the zones. Graph extraction must be useful to scriptwriters at a high-level glance: it should show what the text is about, how blocks and ideas connect, which references or entities recur, and where the user can jump back into the source; regex, stop-word, capitalization, keyword, and hardcoded-domain semantic heuristics are strictly forbidden. The only non-LLM fallback is an explicit user-requested tokenizer/vector similarity mode based on TikToken-style token vectors and distance calculations.
 - Script graph labels, details, semantic scopes, tokenizer chunks, and knowledge-graph markdown input must use compiled TPS display text from the TPS SDK, matching the clean text shown in the prompter; raw TPS source may be used for editor ranges and metadata only, not as a post-hoc string-cleaned source for visible graph prose.
+- Script graph build actions must use the configured LLM extractor when an AI provider is available; tokenizer/vector similarity is only an explicit lower-fidelity fallback button and must not silently replace LLM graph extraction.
 - The AI spotlight action inventory and agent tool inventory are related but separate surfaces: Spotlight suggestions are a macOS-style UI function search over routes and app actions, while agent MCP-style tools are the callable agent contract. Keep both fed from typed descriptors, and every supported agent tool must carry stable names, descriptions, scope, input parameters, MCP safety hints (`read-only`, `idempotent`, `destructive`, `open-world`), and an explicit approval requirement when a call can mutate app or document state.
 - Assistant context must be route-aware. On editor routes, the assistant context must include the current script content, cursor location, selected lines or ranges, and document metadata so rewrite actions can target the intended selection or paragraph instead of replacing the whole script.
 - AI document-editing tools must operate through explicit range-based contracts such as line or character insert, replace, and delete operations; whole-file regeneration is forbidden for partial rewrite requests.

README.md

@@ -54,6 +54,7 @@ No PrompterOne backend. No desktop install. No account wall. Open the app, start
 - **Teleprompter**: read with persisted font and width controls, focal-line positioning, horizontal and vertical mirror toggles, orientation switching, browser fullscreen, segmented progress, and optional camera background.
 - **Onboarding**: walk the first-run flow with a localized tour that explains TPS, RSVP, the editor, Learn, Teleprompter, and Go Live, then reopen that tour later from Settings.
 - **Settings**: manage appearance, browser language, media permissions, camera and microphone setup, sync offsets, recording defaults, AI provider preferences, cloud snapshot targets, transport credentials, and onboarding restart from one routed screen.
+- **AI Spotlight**: when an AI provider is configured, run the global assistant as a real Microsoft Agent Framework agent with route context, editor text, selected ranges, graph summary, and PrompterOne MCP-style tools.
 - **Go Live**: run the browser-owned studio shell and save the composed program feed locally with decodable video and audio while remote transport and destination routing continue to expand.
 
 ## What You Get
@@ -70,7 +71,7 @@ The operating desk for the rest of the app. The library keeps starter scripts an
 
 This is not a plain textarea. The editor understands **TPS** (Teleprompter Script), so you can write in segments, blocks, pacing markers, emphasis, emotion tags, pronunciation guides, pause cues, and speed modifiers directly in the source. Front matter is parsed into the metadata rail and kept out of the visible body instead of lingering inline.
 
-The authoring surface includes structure navigation on the left, a full formatting and insert toolbar, floating selection controls, a metadata rail for front matter and speed offsets, in-document find, import and export actions, browser-local autosave with revision history, syntax-aware highlighting over the live source, and a first-class script graph tab. The graph view can run beside or over the source, lets writers inspect the script's high-level knowledge map, and keeps jump-back-to-source context attached to graph nodes. Recent UI work moved TPS authoring fully onto the Monaco editor surface, tightened dropdown and tooltip behavior, cleaned up gutter spacing, and kept large-draft responsiveness intact on both polished demo scripts and very large seeded drafts.
+The authoring surface includes structure navigation on the left, a full formatting and insert toolbar, floating selection controls, a metadata rail for front matter and speed offsets, in-document find, import and export actions, browser-local autosave with revision history, syntax-aware highlighting over the live source, and a first-class script graph tab. The graph view can run beside or over the source, lets writers inspect the script's high-level knowledge map, and keeps jump-back-to-source context attached to graph nodes. Its **Build AI graph** action uses the configured LLM extractor; tokenizer similarity stays an explicit lower-fidelity fallback instead of silently pretending to be semantic analysis. Recent UI work moved TPS authoring fully onto the Monaco editor surface, tightened dropdown and tooltip behavior, cleaned up gutter spacing, and kept large-draft responsiveness intact on both polished demo scripts and very large seeded drafts.
 
 ![Editor](docs/screenshots/readme/editor.png)
 
@@ -234,7 +235,7 @@ PrompterOne is in **active alpha**: the core authoring, rehearsal, reader, and l
 | **LiveKit transport** | 🟡 | Real transport-aware browser integration and guest-path work, with operational polish still expanding |
 | **Distribution routing** | 🟡 | Targets are capability-gated and blocked when the selected transport cannot service them |
 | **Cloud storage snapshots** | 🟡 | Browser-local provider configuration ships now; broader import/export maturity is still expanding |
-| **AI provider execution** | 🟡 | Provider settings and UI hooks exist, but full runtime execution is still gated behind honest provider integrations |
+| **AI provider execution** | ✅ | AI Spotlight runs a configured Microsoft Agent Framework agent with route/editor context and MCP-style tools; script graph analysis uses the configured LLM extractor before any explicit tokenizer fallback |
 | **Generic RTMP fan-out** | ❌ | Intentionally unsupported without a real upstream transport path |
 | **PrompterOne backend** | ❌ | By design: the browser is the only app runtime |
 
@@ -249,7 +250,7 @@ These are product directions, not release-date promises.
 
 **After that:**
 - Stronger guest and destination-routing workflows on top of the browser studio
-- AI-assisted writing once provider integrations are real enough to document honestly
+- More agent-callable editor, media, and streaming operations on top of the existing AI runtime
 - Deeper operational telemetry and operator ergonomics in Go Live
 
 ## Quick Start

docs/screenshots/readme/tps-cues/32-articulation-legato.png

@@ -0,0 +1,10 @@
+using PrompterOne.Core.AI.Models;
+
+namespace PrompterOne.Core.AI.Abstractions;
+
+public interface IScriptAgentRuntime
+{
+    Task<ScriptAgentRunResult> RunAsync(
+        ScriptAgentRunRequest request,
+        CancellationToken cancellationToken = default);
+}

docs/screenshots/readme/tps-cues/52-phrase-articulation-legato.png

@@ -0,0 +1,26 @@
+namespace PrompterOne.Core.AI.Agents;
+
+public sealed class AssistantScriptAgent : ScriptAgent
+{
+    public const string AgentId = "assistant";
+
+    private static readonly IReadOnlyList<string> AgentSkillIds = [WriterScriptAgent.AgentId, ReviewerScriptAgent.AgentId];
+
+    public override string Id => AgentId;
+
+    public override string Name => "Script Assistant";
+
+    public override string Description => "Answers route-aware questions and uses PrompterOne tools for script work.";
+
+    public override IReadOnlyList<string> SkillIds => AgentSkillIds;
+
+    protected override string SystemPrompt =>
+        """
+        You are the PrompterOne AI assistant.
+        Answer the user's request using the active route, editor context, selected range, graph summary, and available tools.
+        Use MCP-style tools when you need current document text, selected text, graph details, or app action metadata.
+        For partial document edits, work through explicit range-based tool contracts. Do not regenerate a whole script unless the user clearly asks for a full rewrite.
+        If a change would mutate user text, propose a scoped edit and explain the reason clearly.
+        Keep responses concise and directly useful inside the app.
+        """;
+}

src/PrompterOne.Core/AI/Abstractions/IScriptAgentRuntime.cs

@@ -24,6 +24,7 @@ public sealed record ScriptKnowledgeGraphArtifact(
 
 public enum ScriptKnowledgeGraphSemanticMode
 {
+    StructuralOnly,
     ModelOnly,
     TokenizerSimilarity
 }

src/PrompterOne.Core/AI/Agents/AssistantScriptAgent.cs

@@ -9,7 +9,7 @@ namespace PrompterOne.Core.AI.Services;
 public sealed class ScriptAgentRuntime(
     IEnumerable<ScriptAgent> agents,
     IEnumerable<ScriptWorkflow> workflows,
-    IScriptAgentFactory agentFactory)
+    IScriptAgentFactory agentFactory) : IScriptAgentRuntime
 {
     private readonly IReadOnlyDictionary<string, ScriptAgent> _agentsById = agents.ToDictionary(
         static agent => agent.Id,

src/PrompterOne.Core/AI/Models/ScriptKnowledgeGraphModels.cs

@@ -58,15 +58,17 @@ public async Task<ScriptKnowledgeGraphArtifact> BuildAsync(
             edges,
             ranges);
         AddKnowledgeBankGraph(kbResult.Graph.ToSnapshot(), content, nodes, edges, ranges);
-        var semanticStatus = await TryAddModelSemanticGraphAsync(
-                request,
-                compiledDocument.DisplayMarkdown,
-                semanticScopes,
-                nodes,
-                edges,
-                ranges,
-                cancellationToken)
-            .ConfigureAwait(false);
+        var semanticStatus = request.SemanticMode == ScriptKnowledgeGraphSemanticMode.StructuralOnly
+            ? ScriptKnowledgeGraphSemanticStatus.StructuralOnly
+            : await TryAddModelSemanticGraphAsync(
+                    request,
+                    compiledDocument.DisplayMarkdown,
+                    semanticScopes,
+                    nodes,
+                    edges,
+                    ranges,
+                    cancellationToken)
+                .ConfigureAwait(false);
         if (semanticStatus != ScriptKnowledgeGraphSemanticStatus.Model &&
             request.SemanticMode == ScriptKnowledgeGraphSemanticMode.TokenizerSimilarity &&
             await _tokenizerSimilarityExtractor

src/PrompterOne.Core/AI/Services/ScriptAgentRuntime.cs

@@ -0,0 +1,27 @@
+using Microsoft.Agents.AI;
+using PrompterOne.Core.AI.Agents;
+using PrompterOne.Core.AI.Models;
+
+namespace PrompterOne.Core.AI.Workflows;
+
+public sealed class AssistantScriptWorkflow : ScriptWorkflow
+{
+    public const string WorkflowId = "assistant";
+
+    private static readonly IReadOnlyList<string> WorkflowAgentIds = [AssistantScriptAgent.AgentId];
+
+    public override string Id => WorkflowId;
+
+    public override string Name => "Script Assistant";
+
+    public override string Description => "Runs one route-aware assistant agent with PrompterOne context and tools.";
+
+    public override ScriptWorkflowKind Kind => ScriptWorkflowKind.Sequential;
+
+    public override IReadOnlyList<string> AgentIds => WorkflowAgentIds;
+
+    protected override AIAgent BuildWorkflowAgent(IReadOnlyList<AIAgent> agents) =>
+        agents.Count == 1
+            ? agents[0]
+            : throw new InvalidOperationException("The assistant workflow requires exactly one agent.");
+}