@perspective-dev/viewer 5.1.0 → 5.2.0

package/src/rust/agent/runtime.rs

@@ -0,0 +1,201 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use std::rc::Rc;
+
+use perspective_js::utils::{ApiError, ApiResult};
+use wasm_bindgen::prelude::*;
+
+use super::client::{AgentTransport, ChatMessage, OnDelta, TurnError, run_turn};
+use super::config::{AgentConfig, SystemRole};
+use super::docs::DocsCell;
+use super::tools::ToolCtx;
+use crate::custom_elements::viewer::PerspectiveViewerElement;
+
+/// The agent's system preamble — the ONE copy, authored as markdown and
+/// embedded at compile time. This crate knows nothing of its structure:
+/// [`AgentRuntime::preamble`] only chooses between this and a
+/// bundle-supplied override, then appends the host's `systemPrompt`.
+///
+/// Its `search_docs` step is unconditional, which is why `search_docs` is
+/// advertised unconditionally too (an unconfigured corpus searches EMPTY
+/// rather than removing the tool) — one prompt, one tool surface, no
+/// phantom-tool instructions either way.
+const PREAMBLE: &str = include_str!("preamble.md");
+
+/// The model-request budget per `prompt()` call — schema lookup + a few
+/// config patches + expression iteration fit comfortably; overridable via
+/// config `maxTurns`.
+const DEFAULT_MAX_TURNS: usize = 16;
+
+/// One configured agent: connection + conversation history + the tool
+/// handle.
+/// Owned by the element; created by `agentConfig()` and shared by every
+/// `prompt()` call. The history `Mutex` serializes concurrent prompts.
+pub struct AgentRuntime {
+    config: AgentConfig,
+    history: async_lock::Mutex<Vec<ChatMessage>>,
+    elem: PerspectiveViewerElement,
+    docs: Option<Rc<DocsCell>>,
+}
+
+impl AgentRuntime {
+    pub fn new(config: &JsValue, elem: PerspectiveViewerElement) -> ApiResult<Self> {
+        let config = AgentConfig::from_js(config)?;
+        let docs = config.docs.clone().map(|x| Rc::new(DocsCell::new(x)));
+        Ok(Self {
+            config,
+            history: async_lock::Mutex::new(vec![]),
+            elem,
+            docs,
+        })
+    }
+
+    /// Run one conversational turn (which may span many model requests and
+    /// tool calls) and return the final assistant text. History commits on
+    /// success — and on turn-budget exhaustion, whose transcript is coherent
+    /// and whose tool mutations persist in the viewer (see
+    /// [`TurnError::Budget`]); a transport-failed or aborted turn leaves the
+    /// conversation as it was.
+    pub async fn prompt(&self, prompt: String, on_delta: OnDelta<'_>) -> ApiResult<String> {
+        let mut history = self.history.lock().await;
+        let transport = self.transport()?;
+
+        // Resolve the docs metadata bundle BEFORE the first request so the
+        // turn's tool definitions carry the generated parameter schemas
+        // deterministically. A failed load does not abort the turn — the
+        // error is cached and surfaces through `search_docs`.
+        let bundle = match &self.docs {
+            Some(docs) => Some(docs.bundle().await),
+            None => None,
+        };
+
+        let ctx = ToolCtx {
+            docs: self.docs.clone(),
+            bundle,
+            entitlements: self.config.entitlements.clone(),
+        };
+
+        // The preamble is a SYSTEM message by default, but some engines
+        // reject one outright when `tools` is present because they need
+        // to own the system prompt (WebLLM's Hermes function calling
+        // throws `CustomSystemPromptError` on ANY system message, then
+        // substitutes its own carrying the tool definitions). Those
+        // configure `systemRole: "user"`, which folds the same text into
+        // the conversation's opening user turn — sent once, then carried
+        // by history like any other message, which is why nothing is
+        // stripped on commit below.
+        let preamble = self.preamble(&ctx);
+        let mut messages = Vec::with_capacity(history.len() + 2);
+        let preamble_len = match self.config.system_role {
+            SystemRole::System => {
+                messages.push(ChatMessage::System {
+                    content: preamble.clone(),
+                });
+
+                1
+            },
+            SystemRole::User => 0,
+        };
+
+        messages.extend(history.iter().cloned());
+        let content = if preamble_len == 0 && history.is_empty() {
+            format!("{preamble}\n\n{prompt}")
+        } else {
+            prompt
+        };
+
+        messages.push(ChatMessage::User { content });
+        let result = run_turn(
+            &transport,
+            self.config.model_name(),
+            self.config.max_turns.unwrap_or(DEFAULT_MAX_TURNS),
+            &self.elem,
+            &ctx,
+            &mut messages,
+            self.config.system_role,
+            on_delta,
+        )
+        .await;
+
+        match result {
+            Ok(text) => {
+                *history = messages.split_off(preamble_len);
+                Ok(text)
+            },
+            Err(err @ TurnError::Budget { .. }) => {
+                *history = messages.split_off(preamble_len);
+                Err(err.into())
+            },
+            Err(err) => Err(err.into()),
+        }
+    }
+
+    /// Clear the conversation history.
+    pub async fn reset(&self) {
+        self.history.lock().await.clear();
+    }
+
+    /// Connection/model badge text, e.g. `"anthropic · claude-haiku-4-5"`.
+    pub fn label(&self) -> String {
+        format!(
+            "{} · {}",
+            self.config.label_name(),
+            self.config.model_name()
+        )
+    }
+
+    /// Connection fields → transport. `url` XOR `engine` was validated at
+    /// configuration; `apiKey` is Bearer sugar and `headers` pass verbatim.
+    fn transport(&self) -> ApiResult<AgentTransport> {
+        if let Some(engine) = &self.config.engine {
+            return Ok(AgentTransport::Engine(engine.clone()));
+        }
+
+        let url = self
+            .config
+            .url
+            .clone()
+            .ok_or_else(|| ApiError::from("`url` or `engine` is required"))?;
+
+        let mut headers = self
+            .config
+            .headers
+            .clone()
+            .map(|x| x.into_iter().collect::<Vec<_>>())
+            .unwrap_or_default();
+
+        if let Some(key) = &self.config.api_key {
+            headers.push(("authorization".to_owned(), format!("Bearer {key}")));
+        }
+
+        Ok(AgentTransport::Fetch { url, headers })
+    }
+
+    fn preamble(&self, ctx: &ToolCtx) -> String {
+        let mut preamble = ctx
+            .bundle
+            .as_ref()
+            .and_then(|x| x.as_ref().as_ref().ok())
+            .and_then(|x| x.preamble.as_deref())
+            .unwrap_or(PREAMBLE)
+            .trim_end()
+            .to_owned();
+
+        if let Some(extra) = &self.config.system_prompt {
+            preamble.push_str("\n\n");
+            preamble.push_str(extra);
+        }
+
+        preamble
+    }
+}

package/src/rust/agent/slot.rs

@@ -0,0 +1,236 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+//! [`AgentSlot`] — the shared agent model hung off `Presentation`. Holds the
+//! configured [`AgentRuntime`] plus the UI-facing conversation state
+//! (transcript, busy flag, abort handle) OUTSIDE the component tree, so the
+//! chat panel is a pure view that can unmount (tab switch, settings close)
+//! without losing the conversation or interrupting a running turn.
+
+use std::cell::{Cell, RefCell};
+use std::rc::Rc;
+
+use futures::future::{AbortHandle, Abortable};
+use perspective_js::utils::{ApiError, ApiResult};
+
+use super::runtime::AgentRuntime;
+use crate::utils::PubSub;
+
+/// One rendered transcript entry. `Tool` entries are appended live as the
+/// agent works, giving the chat UI its activity feed.
+#[derive(Clone, PartialEq)]
+pub enum ChatEntry {
+    User(String),
+    Assistant {
+        text: String,
+
+        /// Reasoning-model "thinking" captured during the turn —
+        /// display-only (never part of model history).
+        reasoning: Option<String>,
+    },
+    Tool {
+        name: String,
+        args: String,
+
+        /// Set after dispatch when the tool failed; the chip renders in
+        /// the theme error color with this text in its tooltip.
+        error: Option<String>,
+    },
+    Error(String),
+}
+
+/// The in-flight turn's live tail: `(content, reasoning)` accumulated so
+/// far by the streaming transport. View-state only — a turn that aborts
+/// mid-stream discards it, and history is written exclusively from the
+/// turn's final result.
+type PendingTail = (String, String);
+
+#[derive(Clone, Default)]
+pub struct AgentSlot {
+    runtime: Rc<RefCell<Option<Rc<AgentRuntime>>>>,
+    transcript: Rc<RefCell<Vec<ChatEntry>>>,
+    pending: Rc<RefCell<Option<PendingTail>>>,
+    busy: Rc<Cell<bool>>,
+    abort: Rc<RefCell<Option<AbortHandle>>>,
+
+    /// Fires on any observable change: configuration, transcript append,
+    /// streaming delta, busy-flag flip.
+    pub on_update: Rc<PubSub<()>>,
+}
+
+impl PartialEq for AgentSlot {
+    fn eq(&self, rhs: &Self) -> bool {
+        Rc::ptr_eq(&self.runtime, &rhs.runtime)
+    }
+}
+
+impl AgentSlot {
+    /// Install (or replace) the runtime, discarding any in-flight turn and
+    /// the prior conversation.
+    pub fn configure(&self, runtime: AgentRuntime) {
+        self.abort_in_flight();
+        *self.runtime.borrow_mut() = Some(Rc::new(runtime));
+        self.transcript.borrow_mut().clear();
+        *self.pending.borrow_mut() = None;
+        self.on_update.emit(());
+    }
+
+    pub fn is_configured(&self) -> bool {
+        self.runtime.borrow().is_some()
+    }
+
+    pub fn is_busy(&self) -> bool {
+        self.busy.get()
+    }
+
+    /// Provider/model badge text for the chat UI.
+    pub fn label(&self) -> Option<String> {
+        self.runtime.borrow().as_ref().map(|x| x.label())
+    }
+
+    pub fn transcript(&self) -> Vec<ChatEntry> {
+        self.transcript.borrow().clone()
+    }
+
+    /// Append a tool-activity entry (called by the tools themselves).
+    pub fn record_tool(&self, name: &str, args: &serde_json::Value) {
+        self.transcript.borrow_mut().push(ChatEntry::Tool {
+            name: name.to_owned(),
+            args: args.to_string(),
+            error: None,
+        });
+
+        self.on_update.emit(());
+    }
+
+    /// Mark the most recent tool entry failed (called by the dispatcher
+    /// after the tool body settles — dispatch is sequential, so the last
+    /// `Tool` entry is the one that just ran).
+    pub fn record_tool_error(&self, message: &str) {
+        if let Some(ChatEntry::Tool { error, .. }) = self
+            .transcript
+            .borrow_mut()
+            .iter_mut()
+            .rev()
+            .find(|x| matches!(x, ChatEntry::Tool { .. }))
+        {
+            *error = Some(message.to_owned());
+        }
+
+        self.on_update.emit(());
+    }
+
+    /// The in-flight turn's streamed `(content, reasoning)`, if any.
+    pub fn pending(&self) -> Option<(String, String)> {
+        self.pending.borrow().clone()
+    }
+
+    /// Run one agent turn with transcript bookkeeping — the single execution
+    /// path shared by the chat UI and the headless `viewer.agentPrompt()`.
+    /// Errors (including cancellation via [`Self::stop`]) land in the
+    /// transcript AND propagate to the caller. Rejects if a turn is already
+    /// running.
+    pub async fn run_prompt(&self, prompt: String) -> ApiResult<String> {
+        let runtime = self
+            .runtime
+            .borrow()
+            .clone()
+            .ok_or_else(|| ApiError::from("`agentConfig()` has not been called"))?;
+
+        if self.busy.replace(true) {
+            return Err(ApiError::from("A prompt is already running"));
+        }
+
+        let (handle, registration) = AbortHandle::new_pair();
+        *self.abort.borrow_mut() = Some(handle);
+        self.transcript
+            .borrow_mut()
+            .push(ChatEntry::User(prompt.clone()));
+
+        self.on_update.emit(());
+        let on_delta = {
+            let pending = self.pending.clone();
+            let on_update = self.on_update.clone();
+            move |text: &str, reasoning: &str| {
+                *pending.borrow_mut() = Some((text.to_owned(), reasoning.to_owned()));
+                on_update.emit(());
+            }
+        };
+
+        let result = Abortable::new(runtime.prompt(prompt, &on_delta), registration).await;
+        *self.abort.borrow_mut() = None;
+        self.busy.set(false);
+
+        // The tail is view-state; the final entry is written from the
+        // turn's RESULT, keeping only the tail's reasoning (which has no
+        // other channel to the transcript).
+        let reasoning = self
+            .pending
+            .borrow_mut()
+            .take()
+            .map(|(_, x)| x)
+            .filter(|x| !x.is_empty());
+
+        let result = match result {
+            Ok(Ok(text)) => {
+                self.transcript.borrow_mut().push(ChatEntry::Assistant {
+                    text: text.clone(),
+                    reasoning,
+                });
+
+                Ok(text)
+            },
+            Ok(Err(err)) => {
+                self.transcript
+                    .borrow_mut()
+                    .push(ChatEntry::Error(format!("{err}")));
+
+                Err(err)
+            },
+            Err(futures::future::Aborted) => {
+                self.transcript
+                    .borrow_mut()
+                    .push(ChatEntry::Error("Stopped".to_owned()));
+
+                Err(ApiError::from("Stopped"))
+            },
+        };
+
+        self.on_update.emit(());
+        result
+    }
+
+    /// Cancel the in-flight turn (no-op when idle).
+    pub fn stop(&self) {
+        self.abort_in_flight();
+    }
+
+    /// Clear the conversation (model history + transcript), keeping the
+    /// configuration.
+    pub async fn reset(&self) {
+        self.abort_in_flight();
+        let runtime = self.runtime.borrow().clone();
+        if let Some(runtime) = runtime {
+            runtime.reset().await;
+        }
+
+        self.transcript.borrow_mut().clear();
+        *self.pending.borrow_mut() = None;
+        self.on_update.emit(());
+    }
+
+    fn abort_in_flight(&self) {
+        if let Some(handle) = self.abort.borrow_mut().take() {
+            handle.abort();
+        }
+    }
+}