@kevinwang15/byok-ai 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +348 -2
- package/dist/lib/AskAI.d.ts +47 -0
- package/dist/lib/AskAIHistory.d.ts +11 -0
- package/dist/lib/AskAIProvider.d.ts +3 -0
- package/dist/lib/Markdown.d.ts +28 -0
- package/dist/lib/PageElements.d.ts +18 -0
- package/dist/lib/agent.d.ts +50 -0
- package/dist/lib/answer-components.d.ts +36 -0
- package/dist/lib/context.d.ts +56 -0
- package/dist/lib/conversation-files.d.ts +47 -0
- package/dist/lib/history.d.ts +3 -0
- package/dist/lib/images.d.ts +36 -0
- package/dist/lib/index.d.ts +22 -0
- package/dist/lib/index.js +2326 -0
- package/dist/lib/mcp-result.d.ts +6 -0
- package/dist/lib/mount.d.ts +5 -0
- package/dist/lib/page-context.d.ts +98 -0
- package/dist/lib/page-picker.d.ts +6 -0
- package/dist/lib/providers.d.ts +2 -0
- package/dist/lib/rendering-context.d.ts +8 -0
- package/dist/lib/sandbox-worker-BdFlhTIS.js +15 -0
- package/dist/lib/sandbox-worker.d.ts +1 -0
- package/dist/lib/sandbox.d.ts +3 -0
- package/dist/lib/script-runner.d.ts +4 -0
- package/dist/lib/script.d.ts +27 -0
- package/dist/lib/storage.d.ts +35 -0
- package/dist/lib/types.d.ts +113 -0
- package/dist/lib/useAskAIImage.d.ts +9 -0
- package/dist/lib/usePanelLayout.d.ts +53 -0
- package/dist/lib/workspace-tools.d.ts +23 -0
- package/package.json +113 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kevin Wang
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,349 @@
|
|
|
1
|
-
#
|
|
1
|
+
# byok-ai
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An embeddable AI assistant for React apps where users bring their own API key. The agent loop (AI SDK) runs in the browser: it calls the user's chosen provider directly and uses tools from your MCP servers and from the page itself. Components are unstyled Headless UI and assistant-ui primitives; the library ships no CSS.
|
|
4
|
+
|
|
5
|
+
## Run the demo
|
|
6
|
+
|
|
7
|
+
Requires Node 24+ and npm 11+.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm ci
|
|
11
|
+
npm run dev # demo MCP API on :3000 and Vite on :5173
|
|
12
|
+
npm run check # lint, typecheck (incl. tests and e2e), build, unit tests
|
|
13
|
+
npm run test:e2e # Playwright, Chromium (npx playwright install chromium)
|
|
14
|
+
npm run build:lib # dist/lib: the package's code and type declarations (npm pack runs it)
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Open http://127.0.0.1:5173, click Ask AI, choose a provider and paste a key. The demo MCP server offers `search_docs` and `get_current_time`, and the demo assistant has the workspace and images on. If port 3000 is taken: `PORT=3019 API_PROXY_TARGET=http://127.0.0.1:3019 npm run dev`. `npm run build && npm start` serves the built page and `/api/mcp` from one origin. Tests use simulated providers and never call a real one.
|
|
18
|
+
|
|
19
|
+
## Embed
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
npm install @kevinwang15/byok-ai react react-dom @assistant-ui/react @headlessui/react ai markora markora-extension-components
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
The package is an ES module for bundlers (tested with Vite). Its peer dependencies are the packages your app shares with it: React, the two UI libraries its components are built on, `ai` (whose types custom providers and page tools use), and Markora, which renders answers and whose stylesheets your app imports (see Custom UI). Install them at the versions in its `package.json`. The unscoped npm package named `byok-ai` is a different project.
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
import { AskAI } from '@kevinwang15/byok-ai'
|
|
29
|
+
|
|
30
|
+
const servers = [{ id: 'docs', name: 'Docs', url: '/api/mcp' }]
|
|
31
|
+
|
|
32
|
+
export function Page() {
|
|
33
|
+
return <AskAI mcpServers={servers} storageKey="my-app:assistant" />
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`AskAI` renders a trigger button and a modal dialog with provider setup, chat, history and a tools list. On a page that does not otherwise use React, mount it into an element:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
import { mountAskAI } from '@kevinwang15/byok-ai'
|
|
41
|
+
|
|
42
|
+
const assistant = mountAskAI(document.getElementById('assistant')!, { mcpServers: [{ id: 'docs', name: 'Docs', url: '/api/mcp' }] })
|
|
43
|
+
assistant.unmount() // when the host removes it
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Options
|
|
47
|
+
|
|
48
|
+
`AskAI`, `AskAIProvider` and `mountAskAI` take these (`AskAIOptions`):
|
|
49
|
+
|
|
50
|
+
| Option | Default | Meaning |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| `providers` | `defaultProviders` | Provider presets offered in setup. |
|
|
53
|
+
| `mcpServers` | `[]` | MCP servers (`McpServerConfig`) whose tools the model may call. |
|
|
54
|
+
| `clientTools` | `{}` | AI SDK `tool()` definitions that run in the page. |
|
|
55
|
+
| `workspace` | `false` | Per-conversation files in the browser and sandboxed JavaScript over them (see Workspace). |
|
|
56
|
+
| `images` | `false` | Lets the user attach images to messages, for providers that accept them (see Images). |
|
|
57
|
+
| `pageContext` | `false` | Lets the user add elements of the page to a message, for the model to read (see Page context). |
|
|
58
|
+
| `answerComponents` | `[]` | Components the model may place in answers, such as charts (see Answer components). |
|
|
59
|
+
| `componentInstructions` | `true` | Tells the model about `answerComponents`, after `systemPrompt`. |
|
|
60
|
+
| `systemPrompt` | a short built-in prompt | System prompt for every answer. |
|
|
61
|
+
| `storageKey` | `byok-ai:conversations` | localStorage key for conversations and the open one. |
|
|
62
|
+
| `connectionKey` | `${storageKey}:connection` | localStorage key for the provider connection. Must differ from `storageKey`. |
|
|
63
|
+
| `title` | `Ask AI` | Dialog title and accessible name. |
|
|
64
|
+
| `maxSteps` | `8` | Model steps per answer; each step is one model call that may call tools. |
|
|
65
|
+
| `maxOutputTokens` | provider default | Output token limit per step. |
|
|
66
|
+
| `maxToolCalls` | unlimited | Tool calls per answer; after that the model answers without tools. |
|
|
67
|
+
|
|
68
|
+
`AskAI` also takes `components` (see Custom UI) and `children`, which replace the whole default UI.
|
|
69
|
+
|
|
70
|
+
## Providers
|
|
71
|
+
|
|
72
|
+
`defaultProviders` holds four presets, each with an API key field and an editable model ID: OpenAI (`gpt-4.1-mini`), Anthropic (`claude-sonnet-4-5`, sends Anthropic's direct-browser-access header), Google Gemini (`gemini-2.5-flash`), and OpenAI compatible, which adds a base URL (HTTPS, or HTTP for localhost) and makes the key optional.
|
|
73
|
+
|
|
74
|
+
A preset (`ProviderPreset`) has `id`, `name`, `description`, `defaultValues` and `createModel(values)`, which returns any AI SDK language model, and optionally `acceptsImages` (default false; true in the four presets). Describe its form with `fields`, or render your own `Form`, which receives `values` and `onChange(values)`. `connect` rejects missing required `fields`, then calls `validate(values)`; a returned string is shown and blocks the connection. With a custom `Form`, `validate` is the only check.
|
|
75
|
+
|
|
76
|
+
```tsx
|
|
77
|
+
import { createOpenAI } from '@ai-sdk/openai'
|
|
78
|
+
import { AskAI, defaultProviders, type ProviderFormProps, type ProviderPreset } from '@kevinwang15/byok-ai'
|
|
79
|
+
|
|
80
|
+
function GatewayForm({ values, onChange }: ProviderFormProps) {
|
|
81
|
+
return <label>Gateway key
|
|
82
|
+
<input type="password" value={values.apiKey ?? ''} onChange={e => onChange({ ...values, apiKey: e.target.value })} />
|
|
83
|
+
</label>
|
|
84
|
+
}
|
|
85
|
+
const gateway: ProviderPreset = {
|
|
86
|
+
id: 'gateway', name: 'Company gateway', description: 'Use your company-issued key.',
|
|
87
|
+
defaultValues: { model: 'company-model' },
|
|
88
|
+
Form: GatewayForm,
|
|
89
|
+
validate: values => values.apiKey?.trim() ? undefined : 'Enter a key.',
|
|
90
|
+
createModel: values => createOpenAI({ apiKey: values.apiKey, baseURL: 'https://gateway.example.com/v1' }).chat(values.model),
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export const Page = () => <AskAI providers={[...defaultProviders, gateway]} />
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
A saved connection is matched to a preset by `id`; if no preset has that id, setup is shown.
|
|
97
|
+
|
|
98
|
+
## Tools
|
|
99
|
+
|
|
100
|
+
MCP servers are reached over Streamable HTTP. Each `McpServerConfig` has `id` (letters, digits, `_`, `-`), `name`, `url` (relative URLs resolve against the page) and optional `headers`, either a record or an async function called at the start of each answer. Tools are discovered at the start of each answer and named `serverId__toolName`. MCP requests time out after 60 seconds, and Stop cancels them.
|
|
101
|
+
|
|
102
|
+
```tsx
|
|
103
|
+
<AskAI mcpServers={[{
|
|
104
|
+
id: 'account', name: 'Account tools', url: 'https://tools.example.com/mcp',
|
|
105
|
+
headers: async () => ({ Authorization: 'Bearer ' + await getMcpToken() }),
|
|
106
|
+
}]} />
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
The demo backend (`backend/app.ts`) creates a stateless MCP server per POST to `/api/mcp`. It rejects requests whose `Origin` host differs from the request host unless the origin is listed in `MCP_ALLOWED_ORIGINS` (comma-separated; see `.env.example`). It sends no CORS headers, so cross-origin use needs a CORS-capable reverse proxy. Register more tools in `createMcpServer()`.
|
|
110
|
+
|
|
111
|
+
`clientTools` act on the page, such as reading or editing an open document. Names may use letters, digits, `_` and `-`, but not `__`. Pass fresh definitions as page state changes: every call runs the latest one. Adding or removing a name restarts the runtime.
|
|
112
|
+
|
|
113
|
+
```tsx
|
|
114
|
+
import { useState } from 'react'
|
|
115
|
+
import { tool } from 'ai'
|
|
116
|
+
import { z } from 'zod'
|
|
117
|
+
import { AskAI } from '@kevinwang15/byok-ai'
|
|
118
|
+
|
|
119
|
+
export function Editor() {
|
|
120
|
+
const [title, setTitle] = useState('Untitled')
|
|
121
|
+
const clientTools = {
|
|
122
|
+
get_title: tool({ description: 'Read the document title', inputSchema: z.object({}), execute: async () => title }),
|
|
123
|
+
set_title: tool({
|
|
124
|
+
description: 'Rename the document',
|
|
125
|
+
inputSchema: z.object({ title: z.string() }),
|
|
126
|
+
execute: async input => { setTitle(input.title); return { ok: true } },
|
|
127
|
+
}),
|
|
128
|
+
}
|
|
129
|
+
return <AskAI clientTools={clientTools} maxSteps={6} maxToolCalls={10} />
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
On the last step, or once `maxToolCalls` is spent, tools are disabled and the model is told to answer from what it has. If the model stops without writing an answer, it is asked once more without tools. An unfinished answer is never silent: `error` (shown in the chat) says the answer stopped at the output limit, that the assistant used all its steps, or that the model finished without an answer. A failed request shows either "The connection was interrupted" or a general message to check key, model, CORS and MCP; raw provider errors are never shown, since some include keys.
|
|
134
|
+
|
|
135
|
+
## Workspace
|
|
136
|
+
|
|
137
|
+
With `workspace`, each conversation gets a few text files, and the model can run JavaScript over them for calculation and analysis. Large data stays out of the conversation: the model saves a tool's result straight to a file, computes over it, and reads back only the answer.
|
|
138
|
+
|
|
139
|
+
| Tool | Does |
|
|
140
|
+
| --- | --- |
|
|
141
|
+
| `workspace__list_files` | Names and sizes. |
|
|
142
|
+
| `workspace__read_file` | Up to 20,000 characters from an offset, with `nextOffset` when there is more. |
|
|
143
|
+
| `workspace__write_file`, `workspace__delete_file` | Create, replace or delete a file. |
|
|
144
|
+
| `workspace__save_tool_result` | Call another tool (MCP or page) and save its result to a file; returns the size and the first 600 characters. MCP results are saved as their structured content, or their text. |
|
|
145
|
+
| `workspace__run_javascript` | Run code as an async function body with `files.list()`, `files.read(name)`, `files.readJSON(name)`, `files.write(name, textOrValue)`, `files.delete(name)` and `console.log`; returns what it `return`s (JSON, up to 20,000 characters) and the log. |
|
|
146
|
+
|
|
147
|
+
Files live in the origin private file system (OPFS) under `<storageKey>/<conversation id>/files/`: the storage key is the top folder, so apps on one origin keep their files apart, as they do their localStorage keys. They are kept across reloads, never uploaded, and deleted with their conversation. Names are flat (letters, digits, `.`, `-`, `_`). A file holds up to 8 MB, a conversation 200 files and 64 MB (`WORKSPACE_LIMITS`). The tools page lists the open conversation's files, and `useAskAI().workspace` reads them.
|
|
148
|
+
|
|
149
|
+
Scripts run in QuickJS, a separate JavaScript engine compiled to WebAssembly, in a worker started for each run. They see only the files and `console`: no network, DOM, storage, timers or imports. A run is stopped after 10 seconds or at 256 MB of memory (`SCRIPT_LIMITS`), and Stop ends it at once. A script works on a copy, and its writes are saved only if it finishes without an error. The worker and the engine are in a chunk of their own, loaded when the first script runs. Your bundler emits it like any dynamically imported module. A Content-Security-Policy must allow three things: `worker-src blob:` (the worker starts from a `blob:` URL), `connect-src data:` (the engine's WebAssembly is fetched from a `data:` URL) and `script-src 'wasm-unsafe-eval'` (to compile it).
|
|
150
|
+
|
|
151
|
+
The tools are named `workspace__…`, so with `workspace` on, no MCP server may have the id `workspace`.
|
|
152
|
+
|
|
153
|
+
Browsers offer OPFS only in secure contexts: HTTPS, or `localhost`. On a page served over plain HTTP from another host, `workspace` and `images` have no effect: no workspace tools, no attach button. `browserFilesAvailable()` says which applies, so a system prompt can mention the workspace only when it is there.
|
|
154
|
+
|
|
155
|
+
## Images
|
|
156
|
+
|
|
157
|
+
With `images`, and a provider whose preset `acceptsImages`, the user can attach images to a message: with the attach button, by pasting into the message box, or by dropping them on the composer. A message holds up to 4 (`IMAGE_LIMITS`), of up to 20 MB each. Each is prepared when it is added: an image whose longer edge is over 1,568 px, or that is not PNG, JPEG or WebP, is scaled and encoded as PNG (PNG sources) or JPEG. A file the browser can't read, or one too many, is refused with a message where answer errors show.
|
|
158
|
+
|
|
159
|
+
Sent images are kept with their conversation in OPFS (`<storageKey>/<conversation id>/images/`), not in localStorage; the message records only each image's id, name and type. Every later turn sends them to the model again. A provider that doesn't accept images gets a note in their place, as does an image that is no longer stored. Deleting a conversation deletes its images. Images attached but not sent are not saved: they are dropped on reload or when another conversation opens.
|
|
160
|
+
|
|
161
|
+
## Page context
|
|
162
|
+
|
|
163
|
+
With `pageContext`, the user can add elements of the page to a message, and the model reads their data. **Add from page** works like a browser's element inspector. The innermost element under the pointer that can be added is highlighted, and a click adds it.
|
|
164
|
+
|
|
165
|
+
Elements can nest, and any of them can be added: the inner one, the outer one, or both, each from its own pick. The label above the highlight shows the highlighted element's description. When there is an outer or inner element, the label also has ↑ or ↓ buttons, whose names give that element's description. Choose the level in any of these ways:
|
|
166
|
+
|
|
167
|
+
- Press ↑ and ↓, or click the label's ↑ and ↓, to move to the outer or inner element. The label stays where it is, so the buttons can be clicked again.
|
|
168
|
+
- Press Tab and Shift+Tab to go through every addable element in page order, a parent before its children.
|
|
169
|
+
|
|
170
|
+
A click on the highlighted element or on the label's description, or Enter, adds the highlighted element. Escape or a right-click cancels. A message holds up to 8 (`PAGE_CONTEXT_LIMITS`). The composer shows "2 elements", which opens their list with remove buttons. Each one is marked on the page with a border, and a remove button at its top right, while the composer is visible.
|
|
171
|
+
|
|
172
|
+
Only elements the host describes can be added. Any framework can write the attributes (`PAGE_CONTEXT_ATTRIBUTES`):
|
|
173
|
+
|
|
174
|
+
| Attribute | Holds |
|
|
175
|
+
| --- | --- |
|
|
176
|
+
| `data-ai-context` | Required. What the element is, for the user and the model: "Requests per hour, last 24 hours". |
|
|
177
|
+
| `data-ai-context-data` | Optional. The element's data as text. Fine for small data; it sits in the DOM. |
|
|
178
|
+
| `data-ai-context-read` | Optional. A JavaScript expression evaluated in the page when the model reads the element. Its value, or what its promise resolves to, is the data, as JSON. |
|
|
179
|
+
|
|
180
|
+
An element has at most one of the last two. With neither, its description is all there is. An element with both can't be added: the picker passes over it, and the console says why, once. Reading an element gives only its own data, never that of the elements inside it.
|
|
181
|
+
|
|
182
|
+
```tsx
|
|
183
|
+
<section data-ai-context="Requests per hour, last 24 hours" data-ai-context-read="window.dashboard.series('requests')">…</section>
|
|
184
|
+
<table data-ai-context={`Top keys by spend, ${range}`} data-ai-context-read={`MCP("stats__top_keys", { range: ${JSON.stringify(range)} })`}>…</table>
|
|
185
|
+
<span data-ai-context="Selected team" data-ai-context-data={team.name}>{team.name}</span>
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
A read expression runs as page code, in the global scope and in strict mode, with two more names in scope:
|
|
189
|
+
|
|
190
|
+
- `MCP(name, params)` calls one of the answer's MCP tools by its full name (`serverId__toolName`) with an object of arguments, through the same connection and headers as the model's calls. It returns a promise of the tool's structured content, or of its text when it has none, and rejects when the tool reports an error.
|
|
191
|
+
- `element` is the element being read.
|
|
192
|
+
|
|
193
|
+
A read may take 60 seconds, MCP calls included, and Stop stops the answer from waiting for it.
|
|
194
|
+
|
|
195
|
+
The message tells the model which elements were added. For each one it gives the id, the description, and the descriptions of the described elements it is inside, recorded when it was picked:
|
|
196
|
+
|
|
197
|
+
```text
|
|
198
|
+
The user added 2 elements from the page to this message. Read the data of the ones you need with page__read_element:
|
|
199
|
+
- 3f…: "Overview"
|
|
200
|
+
- 9a…: "Requests per hour" (inside "Overview")
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
The data is read later, when the model calls `page__read_element` with an id, so an element whose description says enough costs nothing. The data is read from the page as it is at that moment. The result is saved with the conversation like any tool's, so later turns and reloads keep what was read.
|
|
204
|
+
|
|
205
|
+
A read gives the model up to 20,000 characters of JSON (`PAGE_CONTEXT_LIMITS.resultChars`). Beyond that, the model gets the start of the data and its size. With `workspace` on, it is told to save the read with `workspace__save_tool_result`, which saves all of it to a file to compute over.
|
|
206
|
+
|
|
207
|
+
An id names the element that was picked, while that element is in the document. An element that has been removed, or rendered again as a new node, is no longer on the page, and the model is told so. Keep the elements a user may add mounted while the conversation is about them. Elements not yet sent are dropped on reload or when another conversation opens, as images are.
|
|
208
|
+
|
|
209
|
+
The tools are named `page__…`, so with `pageContext` on, no MCP server may have the id `page`. The default `AskAIPanel` is a modal dialog, so it closes while the user chooses an element and opens again afterwards.
|
|
210
|
+
|
|
211
|
+
The picker and the marks ship no CSS, apart from what places them. Style them by attribute:
|
|
212
|
+
|
|
213
|
+
- `page-picker` covers the viewport. Inside it are `page-picker-highlight`, `page-picker-label` and `page-picker-hint` (a status line).
|
|
214
|
+
- The label holds `page-picker-outer` (↑), `page-picker-description` and `page-picker-inner` (↓). Each button is `hidden` when there is no element in its direction.
|
|
215
|
+
- Each `page-mark` is a fixed box over its element that lets the pointer through. It holds `page-mark-label` and `page-mark-remove`. Give marks a `z-index` below your panel's.
|
|
216
|
+
- A mark whose element is inside another marked element is `data-nested`. It is also `data-crowded` when its top is within its label's height of that element's top, so the two labels and remove buttons would overlap. Move a crowded mark's label and button inside its border.
|
|
217
|
+
- The composer's list is `page-elements`, with `page-elements-summary` and one `page-element` per element. Each holds its description, a `page-element-place` naming the elements it is inside (when it is inside any), and `page-element-remove`.
|
|
218
|
+
|
|
219
|
+
```css
|
|
220
|
+
[data-byok="page-picker-highlight"] { border: 2px solid #7c5cbf; background: #7c5cbf22; }
|
|
221
|
+
[data-byok="page-picker-label"], [data-byok="page-picker-hint"] { background: #222; color: #fff; padding: 4px 8px; }
|
|
222
|
+
[data-byok="page-mark"] { z-index: 40; border: 2px dashed #7c5cbf; }
|
|
223
|
+
[data-byok="page-mark-label"] { position: absolute; bottom: 100%; left: 0; }
|
|
224
|
+
[data-byok="page-mark-remove"] { position: absolute; top: -10px; right: -10px; }
|
|
225
|
+
[data-byok="page-mark"][data-crowded] [data-byok="page-mark-label"] { top: 4px; bottom: auto; left: 4px; }
|
|
226
|
+
[data-byok="page-mark"][data-crowded] [data-byok="page-mark-remove"] { top: 4px; right: 4px; }
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
## Answer components
|
|
230
|
+
|
|
231
|
+
`answerComponents` lets answers show more than Markdown: charts, cards, whatever your app defines. The model writes one as a fenced block naming it, with its props as one JSON object, and the answer renders your component in its place:
|
|
232
|
+
|
|
233
|
+
````markdown
|
|
234
|
+
Error rates rose this week:
|
|
235
|
+
|
|
236
|
+
```component:stat-card
|
|
237
|
+
{"label": "Failed requests", "value": "4.2%", "note": "Up from 1.1%"}
|
|
238
|
+
```
|
|
239
|
+
````
|
|
240
|
+
|
|
241
|
+
```tsx
|
|
242
|
+
import { AskAI, defineAnswerComponent } from '@kevinwang15/byok-ai'
|
|
243
|
+
|
|
244
|
+
const statCard = defineAnswerComponent<{ label: string; value: string; note?: string }>({
|
|
245
|
+
name: 'stat-card',
|
|
246
|
+
label: 'Figure',
|
|
247
|
+
description: 'One figure that matters, with a short label and an optional note.',
|
|
248
|
+
schema: { type: 'object', required: ['label', 'value'], properties: { label: { type: 'string' }, value: { type: 'string' }, note: { type: 'string' } } },
|
|
249
|
+
example: { label: 'Open issues', value: '12' },
|
|
250
|
+
parse: value => {
|
|
251
|
+
const props = value as { label?: unknown; value?: unknown; note?: unknown }
|
|
252
|
+
if (typeof props.label !== 'string' || typeof props.value !== 'string') throw new Error('label and value are text')
|
|
253
|
+
return { label: props.label, value: props.value, ...(typeof props.note === 'string' ? { note: props.note } : {}) }
|
|
254
|
+
},
|
|
255
|
+
render: ({ props }) => <figure><figcaption>{props.label}</figcaption><strong>{props.value}</strong>{props.note && <span>{props.note}</span>}</figure>,
|
|
256
|
+
})
|
|
257
|
+
|
|
258
|
+
export const Page = () => <AskAI answerComponents={[statCard]} />
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
An `AnswerComponent` has a `name` (lower-case kebab case), a `label` for people, a `description`, a JSON Schema `schema` and an `example` for the model, `parse`, which checks props and returns them (or throws), and `render`, a React component that receives `props`. The system prompt gets a section that lists them with their schemas and examples (`answerComponentInstructions(components)` returns it, for a prompt you build yourself; `componentInstructions: false` leaves it out). Components render in your React tree, so they see its context.
|
|
262
|
+
|
|
263
|
+
Props are model output, and tool results can steer it: check them in `parse`, and render them as text, never as HTML or as addresses to load. A component with props that don't parse, or one the app doesn't define, shows a short note in its place. While an answer streams, a component whose block is still open shows as `label…` until it closes.
|
|
264
|
+
|
|
265
|
+
The fence is the component syntax of [Markora](https://github.com/KevinWang15/markora)'s components extension, which renders the answers (see Custom UI), so documents that embed the same components read the same way.
|
|
266
|
+
|
|
267
|
+
## Custom UI
|
|
268
|
+
|
|
269
|
+
`AskAIProvider` holds state and the assistant-ui runtime and renders no DOM. Inside it, `useAskAI()` returns `title`, `providers`, `mcpServers`, `clientTools` (names), `workspace` (the open conversation's files, when on), `images` (whether images can be attached now), `loadImage(id)`, `open`/`setOpen`, `page`/`setPage` (`'chat' | 'settings' | 'history' | 'tools'`), `connection`, `connect(provider, values)` (returns an error string or `undefined`), `disconnect()`, `conversations`, `activeConversation`, `newConversation()`, `selectConversation(id)`, `deleteConversation(id)` (immediate; confirm first), `busy`, `error`, `storageError` and `runtime`. Send with `runtime.thread.append(text)` and stop with `runtime.thread.cancelRun()`. Changing provider, page or conversation is ignored while `busy`.
|
|
270
|
+
|
|
271
|
+
Compose the parts you need: `AskAITrigger` and `AskAIPanel` (native button and div props), `AskAISetup`, `AskAIChat`, `AskAIHistory`, `AskAITools`, `AskAIMessageContent`, `AskAIMessageActions`, or `AskAIWidget` for the full default UI. For page context: `AskAIAddFromPage` (renders nothing while `pageContext` is off), `AskAIComposerElements` (the composer's elements and their marks on the page) and `AskAIMessageElements` (a user message's), each taking `summary(count)` for the "2 elements" text; `useAskAI()` also gives `pageContext`, `picking` and `pickFromPage()`. For images in a custom composer or message: `AskAIAddImage` (the attach button; renders nothing while images can't be attached), `AskAIComposerImages` (attached images with remove buttons), `AskAIMessageImages` (a user message's images), and `useAskAIImage()` for your own thumbnail; wrap the composer's input in `ComposerPrimitive.AttachmentDropzone` for dropping. `createBrowserAdapter` is the assistant-ui `ChatModelAdapter` behind the runtime, for hosts that build their own; it uses `systemPrompt` as given, so add `answerComponentInstructions(components)` to it yourself.
|
|
272
|
+
|
|
273
|
+
```tsx
|
|
274
|
+
import { AskAIChat, AskAIHistory, AskAIPanel, AskAIProvider, AskAISetup, AskAITrigger, useAskAI } from '@kevinwang15/byok-ai'
|
|
275
|
+
|
|
276
|
+
function Shell() {
|
|
277
|
+
const { connection, page, setPage, busy } = useAskAI()
|
|
278
|
+
return <>
|
|
279
|
+
<AskAITrigger className="ask-trigger">Ask</AskAITrigger>
|
|
280
|
+
<AskAIPanel className="ask-panel">
|
|
281
|
+
<button type="button" disabled={busy} onClick={() => setPage(page === 'history' ? 'chat' : 'history')}>History</button>
|
|
282
|
+
{!connection || page === 'settings' ? <AskAISetup /> : page === 'history' ? <AskAIHistory title="Questions about this page" /> : <AskAIChat />}
|
|
283
|
+
</AskAIPanel>
|
|
284
|
+
</>
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
export const Page = () => <AskAIProvider storageKey="my-app:help"><Shell /></AskAIProvider>
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
`components` on `AskAIChat`, `AskAIWidget` and `AskAI` replaces parts of the chat: `Text`, `ToolFallback`, `UserMessage`, `AssistantMessage`, `Empty` and `Composer`. Message slots render inside assistant-ui's message scope; use `AskAIMessageContent` in them to keep the `Text` and `ToolFallback` overrides, and `AskAIMessageActions` for copy and regenerate (labels via `copy`, `copied`, `regenerate`). Define slot components at module scope so they don't remount while streaming.
|
|
291
|
+
|
|
292
|
+
`MarkdownText` is the default `Text`. It renders the current assistant-ui text part with [Markora](https://github.com/KevinWang15/markora), read only: GitHub-flavored Markdown and the provider's `answerComponents`, with raw HTML shown as text. Images in an answer are never loaded: each shows as a placeholder with its description, since tool results can carry text other people wrote, and an answer steered into `` would send the user's data there the moment it loaded. Links are plain anchors to the address `resolveLink(href)` returns for the one written (default: the same), or text when it returns null; the browser's own link behavior (middle-click, "Open in new tab", the status bar) goes there too, so return the address as your app serves it (under its base path, say). `onOpenLink(href, event)` is called with that address when a link is clicked, and `event.preventDefault()` lets you handle it (in-app navigation, a new tab); Ctrl/Cmd-click is Markora's, which opens it in a new tab. It also takes `components` (in place of the provider's), `className` and `label` (the accessible name, default "Answer"). `Markdown` renders any text the same way outside a chat (`markdown`, and `streaming` while it is still being written), for answers you show elsewhere. Like the rest of the library it ships no CSS, but Markora needs its stylesheets for parts of the layout (visually hidden status text, image placeholders, scrolling wide tables), so import them once in your app, with `markora` and `markora-extension-components` installed as direct dependencies (they are peer dependencies):
|
|
293
|
+
|
|
294
|
+
```ts
|
|
295
|
+
import 'markora/styles.css'
|
|
296
|
+
import 'markora-extension-components/styles.css'
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
They are scoped to Markora's element. Style the rest by `[data-byok="markdown"]` and Markora's `mdw-` classes (an answer component sits in `.mdw-component`, under a `.mdw-component-header` naming it, which you may hide).
|
|
300
|
+
|
|
301
|
+
Default components carry `data-byok` attributes for styling (`root`, `trigger`, `dialog`, `panel`, `setup`, `chat`, `messages`, `message` with `data-role`, `composer`, `tool`, `markdown`, `markdown-pending`, `message-actions`, `history`, `tools`, `image` with `data-missing`, `composer-images`, `message-images`, `add-image`, `add-from-page`, the page context parts above, and others). The dialog is portalled to `document.body`, so style it by attribute or class rather than ancestor selectors. `AskAIHistory` takes `title`, `description` and `empty` to replace its copy.
|
|
302
|
+
|
|
303
|
+
`usePanelLayout({ storageKey, margin?, minSize? })` gives a floating panel window behavior: move by dragging the header, resize from any edge or corner, arrow keys on the header or a handle (Shift for bigger steps), Escape to cancel a move, and `toggleMaximized()`. Spread `panelProps` on the panel, `headerProps` on its header and `handleProps(edge)` (`'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw'`) on focusable handles, and apply `style`. It sets `--byok-panel-width`/`--byok-panel-height` (px) once resized and `--byok-panel-x`/`--byok-panel-y` (0 to 1 of the free space) once moved; your CSS turns them into placement. It also returns `maximized`, `positioned`, `resizing` and `moving`.
|
|
304
|
+
|
|
305
|
+
```tsx
|
|
306
|
+
import { AskAIChat, AskAIPanel, usePanelLayout } from '@kevinwang15/byok-ai'
|
|
307
|
+
|
|
308
|
+
export function Window() {
|
|
309
|
+
const layout = usePanelLayout({ storageKey: 'my-app:panel' })
|
|
310
|
+
return <AskAIPanel {...layout.panelProps} style={layout.style}>
|
|
311
|
+
<header {...layout.headerProps}>Ask AI <button type="button" onClick={layout.toggleMaximized}>Maximize</button></header>
|
|
312
|
+
<AskAIChat />
|
|
313
|
+
<button type="button" aria-label="Resize" {...layout.handleProps('se')} />
|
|
314
|
+
</AskAIPanel>
|
|
315
|
+
}
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
## Persistence
|
|
319
|
+
|
|
320
|
+
Everything except workspace files and images (see Workspace and Images) is saved in the browser's localStorage:
|
|
321
|
+
|
|
322
|
+
| Key | Holds |
|
|
323
|
+
| --- | --- |
|
|
324
|
+
| `storageKey` | `{ conversations, activeConversationId }`: messages with tool calls and results, unsent drafts, titles, timestamps |
|
|
325
|
+
| `connectionKey` | `{ providerId, values }`: the chosen preset and its form values, API key included |
|
|
326
|
+
| `usePanelLayout`'s `storageKey` | panel size, position and maximized state |
|
|
327
|
+
|
|
328
|
+
A conversation is listed once it has a message or a non-blank draft. A response still running at reload comes back cancelled. Records of another shape are skipped. Read and write failures never throw; they set `storageError`. Disconnecting removes the saved connection and keeps conversations.
|
|
329
|
+
|
|
330
|
+
Assistants that pass the same `connectionKey` share one connection: connecting or disconnecting in one updates the others, in the same tab and in other tabs. A running answer finishes with the connection it started with. Conversations are not synced across tabs, so give each mounted assistant its own `storageKey`.
|
|
331
|
+
|
|
332
|
+
## Security and browser constraints
|
|
333
|
+
|
|
334
|
+
- API keys are stored in plain text in localStorage. Any script on the same origin can read them; clearing site data removes them. No key is sent to your backend.
|
|
335
|
+
- The provider must accept browser requests (CORS). Providers that don't need a compatible gateway you run.
|
|
336
|
+
- Browsers can't launch stdio MCP servers; expose them over Streamable HTTP.
|
|
337
|
+
- Authenticating users and authorizing tool calls is the MCP server's job. Supply credentials through `headers`.
|
|
338
|
+
- Tools run as soon as the model calls them; there is no approval step. Don't expose tools with effects the user hasn't agreed to.
|
|
339
|
+
- `data-ai-context-read` is page code: it runs with the page's privileges when the model reads an element the user added, and a Content-Security-Policy must allow `'unsafe-eval'` for it. Under a policy without it, the model is told that only the element's description is known. Only your own markup may carry it. HTML from other people (comments, rendered documents) must not: sanitizers such as DOMPurify keep `data-*` attributes by default, so remove `data-ai-context*` from it. The model can read only elements the user added, and can't pass anything to their expressions.
|
|
340
|
+
- Treat answers as untrusted: tool results can carry other people's text. Images in answers aren't loaded (see Custom UI); links need a click. A custom `img` component, or rendering answers as HTML, undoes that.
|
|
341
|
+
- Use one `AskAI` or `mountAskAI` per `storageKey`: two mounted with the same key overwrite each other's conversations.
|
|
342
|
+
- Apps on one origin (paths of a shared host) share localStorage and OPFS. Give each app's `storageKey`, `connectionKey` and `usePanelLayout` key the app's own prefix (`my-app:assistant`); the library stores nothing under any other name. The browser does not keep such apps apart from each other's scripts.
|
|
343
|
+
|
|
344
|
+
## Project layout
|
|
345
|
+
|
|
346
|
+
- `frontend/byok/`: the library (`index.ts` lists the public API).
|
|
347
|
+
- `frontend/App.tsx`, `frontend/demo/`, `frontend/style.css`: the demo page and its styles.
|
|
348
|
+
- `backend/`: the demo MCP server (Fastify, `/api/mcp`, `/health`, static files).
|
|
349
|
+
- `tests/`: unit tests (agent loop over a real MCP transport, storage, history, the workspace and its sandbox, images, page context, the demo backend's origin rule). `e2e/`: Playwright tests of the demo.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
|
|
2
|
+
import { ActionBarPrimitive, ComposerPrimitive } from '@assistant-ui/react';
|
|
3
|
+
import { AskAIHistory } from './AskAIHistory';
|
|
4
|
+
import { AskAIAddFromPage, AskAIComposerElements, AskAIMessageElements } from './PageElements';
|
|
5
|
+
import type { AskAIChatProps, AskAIProps } from './types';
|
|
6
|
+
/** Content renderer for consumer-owned message layouts; retains the chat's Text/Tool overrides. */
|
|
7
|
+
export declare function AskAIMessageContent(): import("react").JSX.Element;
|
|
8
|
+
/**
|
|
9
|
+
* Unstyled actions for the enclosing assistant message: copy its text and regenerate it.
|
|
10
|
+
* Hidden while a response runs; on earlier messages only while hovered or focused.
|
|
11
|
+
* Regenerate is disabled without a provider. `copy`, `copied` and `regenerate` replace the labels.
|
|
12
|
+
* Hidden actions keep their place (`visibility: hidden`, `data-hidden`), so hovering a message
|
|
13
|
+
* never changes the conversation's height or shows and hides its scrollbar.
|
|
14
|
+
*/
|
|
15
|
+
export declare function AskAIMessageActions({ copy, copied, regenerate, style, ...props }: Omit<ComponentPropsWithoutRef<typeof ActionBarPrimitive.Root>, 'children'> & {
|
|
16
|
+
copy?: ReactNode;
|
|
17
|
+
copied?: ReactNode;
|
|
18
|
+
regenerate?: ReactNode;
|
|
19
|
+
}): import("react").JSX.Element;
|
|
20
|
+
/** The images attached in the composer, each with a remove button. Use inside a composer. */
|
|
21
|
+
export declare function AskAIComposerImages(): import("react").JSX.Element;
|
|
22
|
+
/** The images sent with the enclosing user message. */
|
|
23
|
+
export declare function AskAIMessageImages(): import("react").JSX.Element;
|
|
24
|
+
/**
|
|
25
|
+
* Opens the file picker for images. Renders nothing while images can't be attached (the `images`
|
|
26
|
+
* option is off, or the provider doesn't accept them). Pasting into the message box and dropping
|
|
27
|
+
* on `ComposerPrimitive.AttachmentDropzone` attach too.
|
|
28
|
+
*/
|
|
29
|
+
export declare function AskAIAddImage({ children, ...props }: ComponentPropsWithoutRef<typeof ComposerPrimitive.AddAttachment>): import("react").JSX.Element | null;
|
|
30
|
+
/** Unstyled chat orchestration with replaceable message, empty-state, and composer layouts. */
|
|
31
|
+
export declare function AskAIChat({ components }?: AskAIChatProps): import("react").JSX.Element;
|
|
32
|
+
/** Optional provider form. Consumers may instead call useAskAI().connect(). */
|
|
33
|
+
export declare function AskAISetup(): import("react").JSX.Element;
|
|
34
|
+
export { AskAIHistory };
|
|
35
|
+
export { AskAIAddFromPage, AskAIComposerElements, AskAIMessageElements };
|
|
36
|
+
export declare function AskAITools(): import("react").JSX.Element;
|
|
37
|
+
/** Native button props, including className, style, children, and event handlers. */
|
|
38
|
+
export declare function AskAITrigger({ children, onClick, ...props }: ComponentPropsWithoutRef<'button'>): import("react").JSX.Element;
|
|
39
|
+
/**
|
|
40
|
+
* Headless UI dialog: portal, focus management, Escape, and outside-click dismissal. It is modal,
|
|
41
|
+
* so it steps aside while the user chooses an element of the page, and comes back after.
|
|
42
|
+
*/
|
|
43
|
+
export declare function AskAIPanel({ children, ...props }: ComponentPropsWithoutRef<'div'>): import("react").JSX.Element;
|
|
44
|
+
/** A complete default UI using unstyled Headless UI and assistant-ui primitives. */
|
|
45
|
+
export declare function AskAIWidget({ components }?: AskAIChatProps): import("react").JSX.Element;
|
|
46
|
+
/** Convenience composition. Pass children to replace the entire UI. No styles are imported. */
|
|
47
|
+
export declare function AskAI({ children, components, ...options }: AskAIProps): import("react").JSX.Element;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { type ReactNode } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* Semantic history and deletion confirmation. All visual styling belongs to the consumer.
|
|
4
|
+
* `title`, `description` and `empty` replace the copy, such as to say which conversations these are
|
|
5
|
+
* when a host keeps one history per page or document.
|
|
6
|
+
*/
|
|
7
|
+
export declare function AskAIHistory({ title, description, empty }?: {
|
|
8
|
+
title?: ReactNode;
|
|
9
|
+
description?: ReactNode;
|
|
10
|
+
empty?: ReactNode;
|
|
11
|
+
}): import("react").JSX.Element;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { type MouseEvent } from 'react';
|
|
2
|
+
import { type AnswerComponent } from './answer-components';
|
|
3
|
+
export interface MarkdownProps {
|
|
4
|
+
markdown: string;
|
|
5
|
+
/** Components the answer may contain. Default: the enclosing AskAIProvider's `answerComponents`. */
|
|
6
|
+
components?: readonly AnswerComponent[];
|
|
7
|
+
/** While true, a component whose fence is still open shows as pending instead of half-written. */
|
|
8
|
+
streaming?: boolean;
|
|
9
|
+
/**
|
|
10
|
+
* Where a link in the answer goes: given its address as written (Markora has already dropped
|
|
11
|
+
* scripts and other unsafe schemes), the address it opens, or null for none (its text stays, not
|
|
12
|
+
* a link). The anchor carries this address, so a click, a middle-click, "Open in new tab" and the
|
|
13
|
+
* status bar all agree. Read when a link renders. Default: the address as written.
|
|
14
|
+
*/
|
|
15
|
+
resolveLink?: (href: string) => string | null;
|
|
16
|
+
/**
|
|
17
|
+
* Called when a link in the answer is clicked, with the address it opens (`resolveLink`). Call
|
|
18
|
+
* `event.preventDefault()` to handle it yourself, such as in-app navigation. Default: the browser
|
|
19
|
+
* follows it. Ctrl/Cmd-click is Markora's: it opens the address in a new tab, without this call.
|
|
20
|
+
*/
|
|
21
|
+
onOpenLink?: (href: string, event: MouseEvent<HTMLElement>) => void;
|
|
22
|
+
className?: string;
|
|
23
|
+
/** Accessible name. Default "Answer". */
|
|
24
|
+
label?: string;
|
|
25
|
+
}
|
|
26
|
+
export declare function Markdown({ markdown, components: given, streaming, resolveLink, onOpenLink, className, label }: MarkdownProps): import("react").JSX.Element;
|
|
27
|
+
/** Markdown for the enclosing assistant-ui text part: the default `Text` of the chat. */
|
|
28
|
+
export declare function MarkdownText(props: Omit<MarkdownProps, 'markdown' | 'streaming'>): import("react").JSX.Element;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* Starts choosing an element of the page to add to the message. Renders nothing while page
|
|
4
|
+
* context is off; disabled while choosing and without a provider.
|
|
5
|
+
*/
|
|
6
|
+
export declare function AskAIAddFromPage({ children, onClick, ...props }: ComponentPropsWithoutRef<'button'>): import("react").JSX.Element | null;
|
|
7
|
+
/**
|
|
8
|
+
* The page elements in the composer: a summary ("2 elements") that opens their list, each with a
|
|
9
|
+
* remove button, and a mark on the page around each element, with a remove button at its top
|
|
10
|
+
* right. Marks show while this is visible. Use inside a composer; renders nothing while it holds none.
|
|
11
|
+
*/
|
|
12
|
+
export declare function AskAIComposerElements({ summary }: {
|
|
13
|
+
summary?: (count: number) => ReactNode;
|
|
14
|
+
}): import("react").JSX.Element | null;
|
|
15
|
+
/** The page elements sent with the enclosing user message: a summary that opens their list. Renders nothing for none. */
|
|
16
|
+
export declare function AskAIMessageElements({ summary }: {
|
|
17
|
+
summary?: (count: number) => ReactNode;
|
|
18
|
+
}): import("react").JSX.Element | null;
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { type ModelMessage, type ToolSet } from 'ai';
|
|
2
|
+
import type { ChatModelAdapter, ThreadMessage } from '@assistant-ui/react';
|
|
3
|
+
import type { McpServerConfig, ProviderPreset, ProviderValues } from './types';
|
|
4
|
+
import type { ImageStore, Workspace } from './conversation-files';
|
|
5
|
+
import type { ScriptRunner } from './script-runner';
|
|
6
|
+
import { type PageElementRegistry } from './page-context';
|
|
7
|
+
/** Said in place of an image the model can't be given. */
|
|
8
|
+
export declare const IMAGE_NOTES: {
|
|
9
|
+
unsupported: string;
|
|
10
|
+
missing: string;
|
|
11
|
+
};
|
|
12
|
+
/**
|
|
13
|
+
* Preserve interleaved calls/results, and repair calls interrupted before a result arrived. A user
|
|
14
|
+
* message's images come from `images` when the model accepts them; otherwise a note says one was
|
|
15
|
+
* there. Its page elements are listed after its text, as readable when `pageElements` is true.
|
|
16
|
+
*/
|
|
17
|
+
export declare function toModelMessages(messages: readonly ThreadMessage[], options?: {
|
|
18
|
+
images?: {
|
|
19
|
+
store: ImageStore;
|
|
20
|
+
accepted: boolean;
|
|
21
|
+
};
|
|
22
|
+
pageElements?: boolean;
|
|
23
|
+
}): Promise<ModelMessage[]>;
|
|
24
|
+
/** Added to the system prompt for the step that must answer: the tool budget is spent, or it is the last step. */
|
|
25
|
+
export declare const FINAL_STEP_INSTRUCTION = "No more tool calls are available for this answer. Answer now from the results you have, and say briefly what you could not check.";
|
|
26
|
+
/** Shown when a response ended without finishing: cut off by the output limit, or out of steps. */
|
|
27
|
+
export declare const INCOMPLETE_MESSAGES: {
|
|
28
|
+
length: string;
|
|
29
|
+
steps: string;
|
|
30
|
+
empty: string;
|
|
31
|
+
};
|
|
32
|
+
/** Shown when the network dropped during a response, as opposed to a provider or MCP failure. */
|
|
33
|
+
export declare const CONNECTION_LOST_MESSAGE = "The connection was interrupted. Try again.";
|
|
34
|
+
export declare function createBrowserAdapter(options: {
|
|
35
|
+
provider: ProviderPreset;
|
|
36
|
+
values: ProviderValues;
|
|
37
|
+
servers: McpServerConfig[];
|
|
38
|
+
clientTools?: () => ToolSet;
|
|
39
|
+
workspace?: {
|
|
40
|
+
open: () => Workspace;
|
|
41
|
+
run: ScriptRunner;
|
|
42
|
+
};
|
|
43
|
+
images?: ImageStore;
|
|
44
|
+
pageElements?: PageElementRegistry;
|
|
45
|
+
systemPrompt: string;
|
|
46
|
+
maxSteps: number;
|
|
47
|
+
maxOutputTokens?: number;
|
|
48
|
+
maxToolCalls?: number;
|
|
49
|
+
onError: (message: string) => void;
|
|
50
|
+
}): ChatModelAdapter;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import type { ComponentType } from 'react';
|
|
2
|
+
export interface AnswerComponent<Props extends Record<string, unknown> = Record<string, unknown>> {
|
|
3
|
+
/** What the model writes after `component:`. Lower-case kebab case, up to 100 characters. */
|
|
4
|
+
name: string;
|
|
5
|
+
/** A short name for people, shown while the component is being written. */
|
|
6
|
+
label: string;
|
|
7
|
+
/** For the model: what the component shows, and when to use it. */
|
|
8
|
+
description: string;
|
|
9
|
+
/** JSON Schema of the props object, for the model. */
|
|
10
|
+
schema: Record<string, unknown>;
|
|
11
|
+
/** Props the model can copy the shape of. */
|
|
12
|
+
example: Props;
|
|
13
|
+
/** Checks props and returns them, or throws an Error saying what is wrong. Pure and synchronous. */
|
|
14
|
+
parse: (value: unknown) => Props;
|
|
15
|
+
render: ComponentType<{
|
|
16
|
+
props: Props;
|
|
17
|
+
}>;
|
|
18
|
+
}
|
|
19
|
+
/** Types an answer component's props through `parse` and `render`. */
|
|
20
|
+
export declare const defineAnswerComponent: <Props extends Record<string, unknown>>(component: AnswerComponent<Props>) => AnswerComponent;
|
|
21
|
+
/** Throws when names are not kebab case, too long, or used twice. */
|
|
22
|
+
export declare function checkAnswerComponents(components: readonly AnswerComponent[]): void;
|
|
23
|
+
/**
|
|
24
|
+
* What the model is told about `components`, to add to its system prompt; '' when there are none.
|
|
25
|
+
* AskAIProvider adds it on its own (`componentInstructions`); call it when you build the prompt
|
|
26
|
+
* for `createBrowserAdapter` yourself.
|
|
27
|
+
*/
|
|
28
|
+
export declare function answerComponentInstructions(components: readonly AnswerComponent[]): string;
|
|
29
|
+
/**
|
|
30
|
+
* Splits text being streamed before a component fence that is still open, so a half-written
|
|
31
|
+
* component isn't rendered: `shown` is the text before it, `pending` the component's name.
|
|
32
|
+
*/
|
|
33
|
+
export declare function splitOpenComponent(markdown: string): {
|
|
34
|
+
shown: string;
|
|
35
|
+
pending: string | null;
|
|
36
|
+
};
|