@perspective-dev/viewer 5.0.0 → 5.2.0

package/src/rust/agent/client/transport.rs

@@ -0,0 +1,287 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+//! How completion requests move: browser `fetch()` for HTTP providers, or a
+//! host-supplied duck-typed engine object (WebLLM's `MLCEngine`, or the
+//! scripted fake the Playwright specs inject) — the same seam either way,
+//! so the offline specs exercise the identical request/response path the
+//! HTTP providers use.
+//!
+//! Every request asks for `stream: true` and every response path degrades
+//! automatically, so streaming needs no configuration surface: an HTTP
+//! response that is not `text/event-stream` and an engine result that is
+//! not async-iterable are both consumed as complete buffered responses.
+//! Either way the caller receives ONE folded [`ChatMessage`], with
+//! incremental progress reported through `on_delta`.
+
+use perspective_js::utils::{ApiError, ApiResult};
+use wasm_bindgen::prelude::*;
+use wasm_bindgen_futures::JsFuture;
+
+use super::protocol::{ChatChunk, ChatMessage, ChatRequest, ChatResponse, ChunkAccumulator};
+
+/// Live progress callback: `(content_so_far, reasoning_so_far)`.
+pub type OnDelta<'a> = &'a dyn Fn(&str, &str);
+
+/// A configured connection to a completions endpoint. Static dispatch — two
+/// variants don't warrant a trait object.
+pub enum AgentTransport {
+    /// POST to an OpenAI-compatible `/chat/completions` URL with the given
+    /// extra request headers (auth etc.).
+    Fetch {
+        url: String,
+        headers: Vec<(String, String)>,
+    },
+
+    /// An in-page object exposing `chat.completions.create(request)`.
+    /// No bytes leave the page.
+    Engine(JsValue),
+}
+
+impl AgentTransport {
+    /// One completion request, folded to the response message. Cancellation
+    /// is by dropping the returned future (see [`AbortGuard`]).
+    pub async fn create(
+        &self,
+        request: &ChatRequest<'_>,
+        on_delta: OnDelta<'_>,
+    ) -> ApiResult<ChatMessage> {
+        let body = serde_json::to_string(request)?;
+        match self {
+            Self::Fetch { url, headers } => fetch_completion(url, headers, &body, on_delta).await,
+            Self::Engine(engine) => engine_completion(engine, &body, on_delta).await,
+        }
+    }
+}
+
+/// Parse a complete (non-streamed) chat-completions response body.
+fn from_response_text(text: &str) -> ApiResult<ChatMessage> {
+    let response: ChatResponse = serde_json::from_str(text)
+        .map_err(|x| ApiError::from(format!("Malformed completion response: {x}")))?;
+
+    response
+        .choices
+        .into_iter()
+        .next()
+        .map(|x| x.message)
+        .ok_or_else(|| ApiError::from("Completion response has no choices"))
+}
+
+/// Aborts the in-flight browser fetch when dropped, wiring the viewer's
+/// future-cancellation model (`AgentSlot`'s `Abortable`, the chat Stop
+/// button) through to the network layer. The fetch `signal` also covers the
+/// response body stream, so aborting mid-SSE kills the socket — no separate
+/// reader cancel is needed. Aborting an already-settled fetch is a no-op,
+/// so the guard needs no disarm path.
+struct AbortGuard(web_sys::AbortController);
+
+impl Drop for AbortGuard {
+    fn drop(&mut self) {
+        self.0.abort();
+    }
+}
+
+async fn fetch_completion(
+    url: &str,
+    headers: &[(String, String)],
+    body: &str,
+    on_delta: OnDelta<'_>,
+) -> ApiResult<ChatMessage> {
+    let controller = web_sys::AbortController::new()?;
+    let _guard = AbortGuard(controller.clone());
+    let request_headers = web_sys::Headers::new()?;
+    request_headers.append("content-type", "application/json")?;
+    for (name, value) in headers {
+        request_headers.append(name, value)?;
+    }
+
+    let init = web_sys::RequestInit::new();
+    init.set_method("POST");
+    init.set_body(&JsValue::from_str(body));
+    init.set_headers(&request_headers);
+    init.set_signal(Some(&controller.signal()));
+    let request = web_sys::Request::new_with_str_and_init(url, &init)?;
+    let window = web_sys::window().ok_or_else(|| ApiError::from("No `window`"))?;
+    let response: web_sys::Response = JsFuture::from(window.fetch_with_request(&request))
+        .await?
+        .unchecked_into();
+
+    if !response.ok() {
+        let text = JsFuture::from(response.text()?)
+            .await?
+            .as_string()
+            .unwrap_or_default();
+
+        return Err(ApiError::from(format!(
+            "HTTP {} {}: {}",
+            response.status(),
+            response.status_text(),
+            text
+        )));
+    }
+
+    let content_type = response
+        .headers()
+        .get("content-type")?
+        .unwrap_or_default()
+        .to_lowercase();
+
+    if content_type.starts_with("text/event-stream") {
+        stream_sse(&response, on_delta).await
+    } else {
+        // The server ignored `stream: true` — buffered fallback.
+        let text = JsFuture::from(response.text()?)
+            .await?
+            .as_string()
+            .unwrap_or_default();
+
+        from_response_text(&text)
+    }
+}
+
+/// Consume a `text/event-stream` response body, folding each `data:` chunk.
+async fn stream_sse(response: &web_sys::Response, on_delta: OnDelta<'_>) -> ApiResult<ChatMessage> {
+    let stream = response
+        .body()
+        .ok_or_else(|| ApiError::from("Streaming response has no body"))?;
+
+    let reader: web_sys::ReadableStreamDefaultReader = stream.get_reader().unchecked_into();
+    let decoder = web_sys::TextDecoder::new()?;
+    let options = web_sys::TextDecodeOptions::new();
+    options.set_stream(true);
+    let mut buf = String::new();
+    let mut acc = ChunkAccumulator::default();
+    'read: loop {
+        let result = JsFuture::from(reader.read()).await?;
+        let done = js_sys::Reflect::get(&result, &JsValue::from_str("done"))?
+            .as_bool()
+            .unwrap_or(true);
+
+        if done {
+            break;
+        }
+
+        let value: js_sys::Uint8Array =
+            js_sys::Reflect::get(&result, &JsValue::from_str("value"))?.unchecked_into();
+
+        buf.push_str(&decoder.decode_with_u8_array_and_options(&value.to_vec(), &options)?);
+        for payload in drain_sse_data(&mut buf) {
+            if payload == "[DONE]" {
+                break 'read;
+            }
+
+            let chunk: ChatChunk = serde_json::from_str(&payload)
+                .map_err(|x| ApiError::from(format!("Malformed completion chunk: {x}")))?;
+
+            acc.push(chunk);
+            let (content, reasoning) = acc.progress();
+            on_delta(content, reasoning);
+        }
+    }
+
+    Ok(acc.finish())
+}
+
+/// Drain complete SSE frames from `buf`, returning each frame's joined
+/// `data:` payload (multi-`data:` frames join with `\n` per the SSE spec);
+/// the incomplete tail stays in `buf`. Comment lines and other fields are
+/// ignored; CRLF is normalized — a `\r`/`\n` pair split across reads
+/// reunites in `buf` before the next drain sees it.
+fn drain_sse_data(buf: &mut String) -> Vec<String> {
+    if buf.contains("\r\n") {
+        *buf = buf.replace("\r\n", "\n");
+    }
+
+    let mut out = vec![];
+    while let Some(pos) = buf.find("\n\n") {
+        let frame: String = buf.drain(..pos + 2).collect();
+        let mut payload = String::new();
+        for line in frame.lines() {
+            if let Some(rest) = line.strip_prefix("data:") {
+                if !payload.is_empty() {
+                    payload.push('\n');
+                }
+
+                payload.push_str(rest.strip_prefix(' ').unwrap_or(rest));
+            }
+        }
+
+        if !payload.is_empty() {
+            out.push(payload);
+        }
+    }
+
+    out
+}
+
+/// JSON round-trip through `JSON.parse`/`JSON.stringify` so the engine sees
+/// plain JS objects (what WebLLM and the spec fakes expect) and replies
+/// deserialize through the same serde path as HTTP responses. A result
+/// bearing `Symbol.asyncIterator` (WebLLM's `stream: true` shape) is
+/// iterated as chunks; anything else is one complete response.
+async fn engine_completion(
+    engine: &JsValue,
+    body: &str,
+    on_delta: OnDelta<'_>,
+) -> ApiResult<ChatMessage> {
+    let request = js_sys::JSON::parse(body)?;
+    let chat = js_sys::Reflect::get(engine, &JsValue::from_str("chat"))?;
+    let completions = js_sys::Reflect::get(&chat, &JsValue::from_str("completions"))?;
+    let create: js_sys::Function =
+        js_sys::Reflect::get(&completions, &JsValue::from_str("create"))?
+            .dyn_into()
+            .map_err(|_| ApiError::from("`engine.chat.completions.create` is not a function"))?;
+
+    let result = create.call1(&completions, &request)?;
+    let result = JsFuture::from(js_sys::Promise::resolve(&result)).await?;
+    let iterator_fn = js_sys::Reflect::get(&result, js_sys::Symbol::async_iterator().as_ref())?;
+    if !iterator_fn.is_function() {
+        let text = js_sys::JSON::stringify(&result)?
+            .as_string()
+            .ok_or_else(|| ApiError::from("Engine returned an unserializable response"))?;
+
+        return from_response_text(&text);
+    }
+
+    let iterator = iterator_fn
+        .unchecked_into::<js_sys::Function>()
+        .call0(&result)?;
+    let next: js_sys::Function = js_sys::Reflect::get(&iterator, &JsValue::from_str("next"))?
+        .dyn_into()
+        .map_err(|_| ApiError::from("Engine stream iterator has no `next`"))?;
+
+    let mut acc = ChunkAccumulator::default();
+    loop {
+        let step = JsFuture::from(js_sys::Promise::resolve(&next.call0(&iterator)?)).await?;
+        let done = js_sys::Reflect::get(&step, &JsValue::from_str("done"))?
+            .as_bool()
+            .unwrap_or(true);
+
+        if done {
+            break;
+        }
+
+        let value = js_sys::Reflect::get(&step, &JsValue::from_str("value"))?;
+        let text = js_sys::JSON::stringify(&value)?
+            .as_string()
+            .ok_or_else(|| ApiError::from("Engine returned an unserializable chunk"))?;
+
+        let chunk: ChatChunk = serde_json::from_str(&text)
+            .map_err(|x| ApiError::from(format!("Malformed completion chunk: {x}")))?;
+
+        acc.push(chunk);
+        let (content, reasoning) = acc.progress();
+        on_delta(content, reasoning);
+    }
+
+    Ok(acc.finish())
+}

package/src/rust/agent/client/turn.rs

@@ -0,0 +1,174 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+//! The agentic loop: model request → dispatch any tool calls → repeat, until
+//! the model answers in text or the turn budget runs out.
+
+use perspective_js::utils::ApiError;
+use serde_json::json;
+
+use super::protocol::{ChatMessage, ChatRequest};
+use super::transport::{AgentTransport, OnDelta};
+use crate::agent::config::SystemRole;
+use crate::agent::tools::{ToolCtx, tool_definitions, tool_dispatch};
+use crate::custom_elements::viewer::PerspectiveViewerElement;
+
+/// How a turn ended without a final assistant answer. The distinction
+/// matters to the caller's commit decision: on [`TurnError::Budget`] the
+/// transcript is *coherent* (every dispatched tool call has its result) and
+/// the dispatched tools may have mutated the viewer, so the transcript must
+/// be COMMITTED — discarding it would leave the next prompt blind to
+/// mutations that persist on screen (e.g. re-adding a panel the model does
+/// not know it created). [`TurnError::Api`] (transport/protocol failure)
+/// leaves the transcript mid-request and is discarded as before.
+pub enum TurnError {
+    Budget { max_turns: usize },
+    Api(ApiError),
+}
+
+impl From<ApiError> for TurnError {
+    fn from(err: ApiError) -> Self {
+        Self::Api(err)
+    }
+}
+
+impl From<TurnError> for ApiError {
+    fn from(err: TurnError) -> Self {
+        match err {
+            TurnError::Budget { max_turns } => ApiError::from(format!(
+                "Turn budget exhausted after {max_turns} model requests (see `maxTurns`)"
+            )),
+            TurnError::Api(err) => err,
+        }
+    }
+}
+
+/// Appended (transiently — never committed to the durable transcript) to
+/// the turn's final budgeted request, so the model answers instead of
+/// starting tool work it cannot finish.
+const BUDGET_NUDGE: &str = "This is the final model request of this turn's budget. Do not call \
+                            more tools - answer now with a short summary of what was done and \
+                            what, if anything, remains.";
+
+/// Run one conversational turn, mutating `messages` (system prompt at index
+/// 0, then transcript) in place with everything the model and tools said.
+/// Tool *failures* are fed back to the model as error tool-results so it can
+/// self-correct; transport and protocol failures abort the turn mid-request,
+/// while turn-budget exhaustion ends it with a coherent transcript — see
+/// [`TurnError`] for the commit consequences.
+#[allow(clippy::too_many_arguments)]
+pub async fn run_turn(
+    transport: &AgentTransport,
+    model: &str,
+    max_turns: usize,
+    elem: &PerspectiveViewerElement,
+    ctx: &ToolCtx,
+    messages: &mut Vec<ChatMessage>,
+    system_role: SystemRole,
+    on_delta: OnDelta<'_>,
+) -> Result<String, TurnError> {
+    let defs = tool_definitions(ctx);
+    for turn in 0..max_turns {
+        // Each model request streams into a fresh tail — reset the live
+        // view so a prior request's partial text does not linger across
+        // tool rounds.
+        on_delta("", "");
+        let nudged;
+        let request_messages: &[ChatMessage] = if turn + 1 == max_turns && max_turns > 1 {
+            let mut with_nudge = messages.clone();
+
+            // Follows the preamble's placement: an engine that rejects a
+            // system message alongside `tools` rejects THIS one too, and
+            // it is appended to the very request that most needs to
+            // succeed.
+            with_nudge.push(match system_role {
+                SystemRole::System => ChatMessage::System {
+                    content: BUDGET_NUDGE.to_owned(),
+                },
+                SystemRole::User => ChatMessage::User {
+                    content: BUDGET_NUDGE.to_owned(),
+                },
+            });
+
+            nudged = with_nudge;
+            &nudged
+        } else {
+            messages
+        };
+
+        let request = ChatRequest {
+            model,
+            messages: request_messages,
+            tools: &defs,
+            stream: true,
+        };
+
+        let message = transport.create(&request, on_delta).await?;
+        let ChatMessage::Assistant {
+            content,
+            tool_calls,
+            reasoning_content,
+        } = message
+        else {
+            return Err(
+                ApiError::from("Completion response message role is not `assistant`").into(),
+            );
+        };
+
+        if tool_calls.is_empty() {
+            let text = content.unwrap_or_default();
+
+            // The buffered fallback never fired `on_delta` — surface the
+            // final text (and any reasoning) so the live view converges on
+            // what history records regardless of transport path.
+            on_delta(&text, reasoning_content.as_deref().unwrap_or_default());
+            messages.push(ChatMessage::Assistant {
+                content: Some(text.clone()),
+                tool_calls: vec![],
+                reasoning_content,
+            });
+
+            return Ok(text);
+        }
+
+        messages.push(ChatMessage::Assistant {
+            content,
+            tool_calls: tool_calls.clone(),
+            reasoning_content,
+        });
+
+        // TODO: There is deliberately no duplicate-call breaker here: a
+        // tool call identical (name + arguments) to one already made this
+        // turn is re-dispatched verbatim, so a model stuck at a fixed
+        // point burns budget until the nudge/exhaustion path ends the
+        // turn (observed in the field: qwen looping `validate_expression`
+        // to `maxTurns`). If nudge + budget prove insufficient, the
+        // breaker is: synthesize an error result ("already called with
+        // identical arguments; the result will not change") without
+        // dispatching.
+        for call in tool_calls {
+            let content =
+                match tool_dispatch(elem, ctx, &call.function.name, &call.function.arguments).await
+                {
+                    Ok(value) => value.to_string(),
+                    Err(err) => json!({ "error": format!("{err}") }).to_string(),
+                };
+
+            messages.push(ChatMessage::Tool {
+                tool_call_id: call.id,
+                content,
+            });
+        }
+    }
+
+    Err(TurnError::Budget { max_turns })
+}

package/src/rust/agent/config.rs

@@ -0,0 +1,159 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+//! `agentConfig()` parsing. There is no provider abstraction in the core —
+//! the client speaks one protocol (OpenAI chat-completions) over primitive
+//! connection fields (`url` + `headers` + `apiKey`, or an in-page
+//! `engine`), and "providers" are plain JSON presets in the JS package
+//! spread into the config (`{...providers.anthropic, apiKey}`).
+
+use std::collections::HashMap;
+
+use perspective_js::utils::{ApiError, ApiResult};
+use serde::Deserialize;
+use wasm_bindgen::prelude::*;
+
+use super::tools::Entitlement;
+
+/// The serde-compatible subset of the `agentConfig()` argument; the
+/// `engine` and `docs` fields are live JS values (an engine object; a
+/// fetch `Response`/buffer/promise or entry array) and are extracted
+/// separately by reference.
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct AgentConfigFields {
+    /// Cosmetic label for the chat badge (presets set this).
+    name: Option<String>,
+
+    /// Full chat-completions endpoint URL, e.g.
+    /// `https://api.anthropic.com/v1/chat/completions`.
+    url: Option<String>,
+
+    /// Extra request headers sent verbatim (e.g. Anthropic's
+    /// `anthropic-dangerous-direct-browser-access`).
+    headers: Option<HashMap<String, String>>,
+
+    /// Sugar for `Authorization: Bearer <apiKey>` — verified accepted by
+    /// every supported OpenAI-compat endpoint (incl. Anthropic + Gemini).
+    api_key: Option<String>,
+
+    model: Option<String>,
+    system_prompt: Option<String>,
+    system_role: Option<SystemRole>,
+    max_turns: Option<usize>,
+
+    /// Access grants (snake_case [`Entitlement`] names); omitted ⇒ the
+    /// default set (everything except `read_data`).
+    entitlements: Option<Vec<String>>,
+}
+
+/// Where the preamble (plus any `systemPrompt`) is placed in a request.
+///
+/// Some engines refuse to accept a system message alongside `tools`
+/// because they need to own the system prompt themselves — WebLLM's
+/// Hermes function-calling rejects the whole request with
+/// `CustomSystemPromptError`. [`SystemRole::User`] folds the same text
+/// into the conversation's first USER message instead, which those
+/// engines accept and which reads identically to the model.
+#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq)]
+#[serde(rename_all = "lowercase")]
+pub enum SystemRole {
+    #[default]
+    System,
+    User,
+}
+
+/// Parsed `viewer.agentConfig({...})` argument.
+pub struct AgentConfig {
+    pub name: Option<String>,
+    pub url: Option<String>,
+    pub headers: Option<HashMap<String, String>>,
+    pub api_key: Option<String>,
+    pub model: Option<String>,
+    pub system_prompt: Option<String>,
+    pub system_role: SystemRole,
+    pub max_turns: Option<usize>,
+    pub entitlements: Vec<Entitlement>,
+    pub engine: Option<JsValue>,
+    pub docs: Option<JsValue>,
+}
+
+impl AgentConfig {
+    pub fn from_js(config: &JsValue) -> ApiResult<Self> {
+        let fields: AgentConfigFields = serde_wasm_bindgen::from_value(config.clone())?;
+        let engine = js_sys::Reflect::get(config, &JsValue::from_str("engine"))
+            .ok()
+            .filter(|x| !x.is_undefined() && !x.is_null());
+
+        let docs = js_sys::Reflect::get(config, &JsValue::from_str("docs"))
+            .ok()
+            .filter(|x| !x.is_undefined() && !x.is_null() && x.as_bool() != Some(false));
+
+        match (&fields.url, &engine) {
+            (Some(_), Some(_)) => {
+                return Err(ApiError::from("Pass either `url` or `engine`, not both"));
+            },
+            (None, None) => {
+                return Err(ApiError::from(
+                    "Either `url` (a chat-completions endpoint, e.g. a spread provider preset) or \
+                     `engine` (an in-page engine object) is required",
+                ));
+            },
+            _ => (),
+        }
+
+        let entitlements = match fields.entitlements {
+            None => Entitlement::default_set(),
+            Some(names) => names
+                .iter()
+                .map(|x| x.parse())
+                .collect::<Result<Vec<_>, _>>()
+                .map_err(ApiError::from)?,
+        };
+
+        Ok(Self {
+            name: fields.name,
+            url: fields.url,
+            headers: fields.headers,
+            api_key: fields.api_key,
+            model: fields.model,
+            system_prompt: fields.system_prompt,
+            system_role: fields.system_role.unwrap_or_default(),
+            max_turns: fields.max_turns,
+            entitlements,
+            engine,
+            docs,
+        })
+    }
+
+    /// The model id sent on every completion request. Local servers and
+    /// in-page engines generally answer with whatever model they have
+    /// loaded, so the fallback is a placeholder.
+    pub fn model_name(&self) -> &str {
+        self.model.as_deref().unwrap_or("default")
+    }
+
+    /// Chat-badge text: the preset `name`, else the endpoint host, else
+    /// `"engine"`.
+    pub fn label_name(&self) -> String {
+        if let Some(name) = &self.name {
+            return name.clone();
+        }
+
+        self.url
+            .as_deref()
+            .and_then(|x| x.split("//").nth(1))
+            .and_then(|x| x.split('/').next())
+            .map(str::to_owned)
+            .unwrap_or_else(|| "engine".to_owned())
+    }
+}