Ian/playground UI

.cursor/rules/convex_rules.mdc

@@ -1,6 +1,7 @@
 ---
 description: Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples
-globs: **/*.{ts,tsx,js,jsx}
+globs: **/*.ts,**/*.tsx,**/*.js,**/*.jsx
+alwaysApply: false
 ---
 
 # Convex guidelines
@@ -85,6 +86,19 @@ globs: **/*.{ts,tsx,js,jsx}
                                     },
                                   });
                                   ```
+- Here are the valid Convex types along with their respective validators:
+ Convex Type  | TS/JS type  |  Example Usage         | Validator for argument validation and schemas  | Notes                                                                                                                                                                                                 |
+| ----------- | ------------| -----------------------| -----------------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Id          | string      | `doc._id`              | `v.id(tableName)`                              |                                                                                                                                                                                                       |
+| Null        | null        | `null`                 | `v.null()`                                     | JavaScript's `undefined` is not a valid Convex value. Functions the return `undefined` or do not return will return `null` when called from a client. Use `null` instead.                             |
+| Int64       | bigint      | `3n`                   | `v.int64()`                                    | Int64s only support BigInts between -2^63 and 2^63-1. Convex supports `bigint`s in most modern browsers.                                                                                              |
+| Float64     | number      | `3.1`                  | `v.number()`                                   | Convex supports all IEEE-754 double-precision floating point numbers (such as NaNs). Inf and NaN are JSON serialized as strings.                                                                      |
+| Boolean     | boolean     | `true`                 | `v.boolean()`                                  |
+| String      | string      | `"abc"`                | `v.string()`                                   | Strings are stored as UTF-8 and must be valid Unicode sequences. Strings must be smaller than the 1MB total size limit when encoded as UTF-8.                                                         |
+| Bytes       | ArrayBuffer | `new ArrayBuffer(8)`   | `v.bytes()`                                    | Convex supports first class bytestrings, passed in as `ArrayBuffer`s. Bytestrings must be smaller than the 1MB total size limit for Convex types.                                                     |
+| Array       | Array]      | `[1, 3.2, "abc"]`      | `v.array(values)`                              | Arrays can have at most 8192 values.                                                                                                                                                                  |
+| Object      | Object      | `{a: "abc"}`           | `v.object({property: value})`                  | Convex only supports "plain old JavaScript objects" (objects that do not have a custom prototype). Objects can have at most 1024 entries. Field names must be nonempty and not start with "$" or "_". |
+| Record      | Record      | `{"a": "1", "b": "2"}` | `v.record(keys, values)`                       | Records are objects at runtime, but can have dynamic keys. Keys must be only ASCII characters, nonempty, and not start with "$" or "_".                                                               |
 
 ### Function registration
 - Use `internalQuery`, `internalMutation`, and `internalAction` to register internal functions. These functions are private and aren't part of an app's API. They can only be called by other Convex functions. These functions are always imported from `./_generated/server`.
@@ -152,6 +166,9 @@ globs: **/*.{ts,tsx,js,jsx}
                                 },
                             });
                             ```
+                            Note: `paginationOpts` is an object with the following properties:
+                            - `numItems`: the maximum number of documents to return (the validator is `v.number()`)
+                            - `cursor`: the cursor to use to fetch the next page of documents (the validator is `v.union(v.string(), v.null())`)
 - A query that ends in `.paginate()` returns an object that has the following properties:
                             - page (contains an array of documents that you fetches)
                             - isDone (a boolean that represents whether or not this is the last page of documents)
@@ -165,7 +182,7 @@ globs: **/*.{ts,tsx,js,jsx}
 ## Schema guidelines
 - Always define your schema in `convex/schema.ts`.
 - Always import the schema definition functions from `convex/server`:
-- System fields are automatically added to all documents and are prefixed with an underscore.
+- System fields are automatically added to all documents and are prefixed with an underscore. The two system fields that are automatically added to all documents are `_creationTime` which has the validator `v.number()` and `_id` which has the validator `v.id(tableName)`.
 - Always include all index fields in the index name. For example, if an index is defined as `["field1", "field2"]`, the index name should be "by_field1_and_field2".
 - Index fields must be queried in the same order they are defined. If you want to be able to query by "field1" then "field2" and by "field2" then "field1", you must create separate indexes.
 
@@ -301,13 +318,13 @@ const messages = await ctx.db
 
 
 # Examples:
-## Example: thread-app
+## Example: chat-app
 
 ### Task
 ```
-Create a real-time thread application backend with AI responses. The app should:
+Create a real-time chat application backend with AI responses. The app should:
 - Allow creating users with names
-- Support multiple thread channels
+- Support multiple chat channels
 - Enable users to send messages to channels
 - Automatically generate AI responses to user messages
 - Show recent message history
@@ -325,7 +342,7 @@ and limit history display to the 10 most recent messages per channel.
 
 ### Analysis
 1. Task Requirements Summary:
-- Build a real-time thread backend with AI integration
+- Build a real-time chat backend with AI integration
 - Support user creation
 - Enable channel-based conversations
 - Store and retrieve messages with proper ordering
@@ -414,8 +431,8 @@ Internal Functions:
 #### package.json
 ```typescript
 {
-  "name": "thread-app",
-  "description": "This example shows how to build a thread app without authentication.",
+  "name": "chat-app",
+  "description": "This example shows how to build a chat app without authentication.",
   "version": "1.0.0",
   "dependencies": {
     "convex": "^1.17.4",

.github/workflows/deploy.yml

@@ -0,0 +1,55 @@
+name: Deploy Playground to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - ian/playground-ui
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install root dependencies
+        run: npm ci
+
+      - name: Install playground dependencies
+        run: cd playground && npm ci
+
+      - name: Build Vite project
+        run: cd playground && VITE_BASE=/agent/ npm run build
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: playground/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.0.17 alpha
+
+- UI Playground, to host locally or embed into your app.
+  - On the left panel it has a dropdown to select a users, then lists the user's treads
+  - In the middle you can see the thread's messages and tool calls
+  - On the right you can see the selected message's details, as well as:
+    - Fetch context messages with different ContextOptions
+    - Send a message in the thread - optionally saving it to the thread.
+  - Run it with `npx @convex-dev/agent-playground` - uses Vite internally for now.
+- Add a function to turn MessageDoc[] into UIMessage[].
+- API key management (to authenticate into the UI Playground)
+- The README is a better resource.
+- Fixes a bug to increment stepOrder correctly.
+
+### Breaking
+
+- `agent.fetchContextMessages` now returns `MessageDoc` instead of a `CoreMessage` objects.
+- `isTool` configuration for context has been changed to `excludeToolMessages` - where `false`/`undefined` is the default and includes tool messages, and `true` will only return user/assistant messages.
+- Reorganization of API (split `agent.messages.*` into `agent.threads.*`, `agent.messages.*`, `agent.files.*`, and `agent.users.*`.
+- Parameters like `parentMessageId` have generally been renamed to `beforeMessageId` to better clarify their use for things like looking up context. The `generate*` / `stream*` functions do not take a parentMessageId.
+- Calls to steps and objects now take a parentMessageId instead of messageId parameter, as this is the true meaning of parent message (the message being responded to).
+
+## 0.0.16
+
+- Fixes a bug with providing out-of-order tool messages in the prompt context. (author: @apostolisCodpal)
+
 ## 0.0.15
 
 - You can pass tools at the agent definition, thread definition, or per-message call, making it easier to define tools at runtime with runtime context.
@@ -13,9 +39,9 @@
 ### Deprecated
 
 - Passing `ConfigOptions` and `StorageOptions` should now be passed as separate parameters via `configOptions` and `storageOptions`.
-e.g. for `generateText`
-`{ prompt }, { contextOptions: { recentMessages: 10 } }` instead of
-`{ prompt, recentMessages: 10 }`
+  e.g. for `generateText`
+  `{ prompt }, { contextOptions: { recentMessages: 10 } }` instead of
+  `{ prompt, recentMessages: 10 }`
 
 ## 0.0.14
 
@@ -30,4 +56,3 @@ e.g. for `generateText`
 ### Deprecated
 
 - parentThreadIds is deprecated, as it wasn't merging histories and the desire to do so should have a message as its parent to make the history behavior clear.
-