@rool-dev/sdk 0.3.1 → 0.3.2-dev.960610c
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/README.md +119 -163
- package/dist/apps.d.ts +1 -1
- package/dist/apps.d.ts.map +1 -1
- package/dist/apps.js +1 -5
- package/dist/apps.js.map +1 -1
- package/dist/channel.d.ts +136 -4
- package/dist/channel.d.ts.map +1 -1
- package/dist/channel.js +373 -32
- package/dist/channel.js.map +1 -1
- package/dist/client.d.ts +18 -2
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +26 -7
- package/dist/client.js.map +1 -1
- package/dist/graphql.d.ts +18 -11
- package/dist/graphql.d.ts.map +1 -1
- package/dist/graphql.js +91 -31
- package/dist/graphql.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/space.d.ts +0 -1
- package/dist/space.d.ts.map +1 -1
- package/dist/space.js.map +1 -1
- package/dist/subscription.d.ts +6 -0
- package/dist/subscription.d.ts.map +1 -1
- package/dist/subscription.js +66 -6
- package/dist/subscription.js.map +1 -1
- package/dist/types.d.ts +144 -25
- package/dist/types.d.ts.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -4,18 +4,14 @@ The TypeScript SDK for Rool, a persistent and collaborative environment for orga
|
|
|
4
4
|
|
|
5
5
|
> **Building a new Rool app?** Start with [`@rool-dev/app`](/app/) — it handles hosting, dev server, and gives you a reactive Svelte channel out of the box. This SDK is for advanced use cases: integrating Rool into an existing application, building Node.js scripts, or working outside the app sandbox.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The SDK manages authentication, real-time synchronization, and media storage. Core primitives:
|
|
8
8
|
|
|
9
|
-
Use Rool to programmatically instruct agents to generate content, research topics, or reorganize data. The client manages authentication, real-time synchronization, and media storage, supporting both single-user and multi-user workflows.
|
|
10
|
-
|
|
11
|
-
**Core primitives:**
|
|
12
9
|
- **Spaces** — Containers for objects, schema, metadata, and channels
|
|
13
|
-
- **Channels** — Named contexts within a space
|
|
10
|
+
- **Channels** — Named contexts within a space. All object and AI operations go through a channel.
|
|
11
|
+
- **Conversations** — Independent interaction histories within a channel.
|
|
14
12
|
- **Objects** — Key-value records with any fields you define. References between objects are data fields whose values are object IDs.
|
|
15
13
|
- **AI operations** — Create, update, or query objects using natural language and `{{placeholders}}`
|
|
16
14
|
|
|
17
|
-
See [Patterns & Examples](#patterns--examples) for what you can build.
|
|
18
|
-
|
|
19
15
|
## Installation
|
|
20
16
|
|
|
21
17
|
```bash
|
|
@@ -84,7 +80,7 @@ channel.close();
|
|
|
84
80
|
|
|
85
81
|
### Spaces and Channels
|
|
86
82
|
|
|
87
|
-
A **space** is a container that holds objects, schema, metadata, and channels. A **channel** is a named context within a space — it's the handle you use for all object and AI operations. Each channel
|
|
83
|
+
A **space** is a container that holds objects, schema, metadata, and channels. A **channel** is a named context within a space — it's the handle you use for all object and AI operations. Each channel contains one or more **conversations**, each with independent interaction history.
|
|
88
84
|
|
|
89
85
|
There are two main handles:
|
|
90
86
|
- **`RoolSpace`** — Lightweight admin handle for user management, link access, channel management, and export. No real-time subscription.
|
|
@@ -111,22 +107,56 @@ The `channelId` is fixed when you open a channel and cannot be changed. To use a
|
|
|
111
107
|
- 1–32 characters
|
|
112
108
|
- Only alphanumeric characters, hyphens (`-`), and underscores (`_`)
|
|
113
109
|
|
|
110
|
+
### Conversations
|
|
111
|
+
|
|
112
|
+
A **conversation** is a named interaction history within a channel. By default, all operations use the `'default'` conversation — most apps never need to think about conversations at all.
|
|
113
|
+
|
|
114
|
+
For apps that need multiple independent interaction threads (e.g., a chat sidebar with multiple threads), use `channel.conversation()` to get a handle scoped to a specific conversation:
|
|
115
|
+
|
|
116
|
+
```typescript
|
|
117
|
+
// Default conversation — most apps use this
|
|
118
|
+
const channel = await client.openChannel('space-id', 'main');
|
|
119
|
+
await channel.prompt('Hello'); // Uses 'default' conversation
|
|
120
|
+
|
|
121
|
+
// Conversation handle — for multi-thread UIs
|
|
122
|
+
const thread = channel.conversation('thread-42');
|
|
123
|
+
await thread.prompt('Hello'); // Uses 'thread-42' conversation
|
|
124
|
+
thread.getInteractions(); // Interactions for thread-42 only
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Each conversation has its own interaction history and optional system instruction. Conversations are auto-created on first interaction — no explicit create step needed. The 50-message cap applies per conversation. All conversations share one SSE connection per channel.
|
|
128
|
+
|
|
129
|
+
```typescript
|
|
130
|
+
// System instructions are per-conversation
|
|
131
|
+
const thread = channel.conversation('research');
|
|
132
|
+
await thread.setSystemInstruction('Respond in haiku');
|
|
133
|
+
|
|
134
|
+
// List all conversations in this channel
|
|
135
|
+
const conversations = channel.getConversations();
|
|
136
|
+
|
|
137
|
+
// Delete a conversation (cannot delete 'default')
|
|
138
|
+
await channel.deleteConversation('old-thread');
|
|
139
|
+
|
|
140
|
+
// Rename a conversation
|
|
141
|
+
await thread.rename('Research Thread');
|
|
142
|
+
```
|
|
143
|
+
|
|
114
144
|
### Objects & References
|
|
115
145
|
|
|
116
146
|
**Objects** are plain key-value records. The `id` field is reserved; everything else is application-defined.
|
|
117
147
|
|
|
118
148
|
```typescript
|
|
119
|
-
{ id: 'abc123',
|
|
149
|
+
{ id: 'abc123', title: 'Hello World', status: 'draft' }
|
|
120
150
|
```
|
|
121
151
|
|
|
122
152
|
**References** between objects are data fields whose values are object IDs. The system detects these statistically — any string field whose value matches an existing object ID is recognized as a reference.
|
|
123
153
|
|
|
124
154
|
```typescript
|
|
125
155
|
// A planet references a star via the 'orbits' field
|
|
126
|
-
{ id: 'earth',
|
|
156
|
+
{ id: 'earth', name: 'Earth', orbits: 'sun-01' }
|
|
127
157
|
|
|
128
158
|
// An array of references
|
|
129
|
-
{ id: 'team-a',
|
|
159
|
+
{ id: 'team-a', name: 'Alpha', members: ['user-1', 'user-2', 'user-3'] }
|
|
130
160
|
```
|
|
131
161
|
|
|
132
162
|
References are just data — no special API is needed to create or remove them. Set a field to an object ID to create a reference; clear it to remove it.
|
|
@@ -139,7 +169,6 @@ Use `{{description}}` in field values to have AI generate content:
|
|
|
139
169
|
// Create with AI-generated content
|
|
140
170
|
await channel.createObject({
|
|
141
171
|
data: {
|
|
142
|
-
type: 'article',
|
|
143
172
|
headline: '{{catchy headline about coffee}}',
|
|
144
173
|
body: '{{informative paragraph}}'
|
|
145
174
|
}
|
|
@@ -235,7 +264,7 @@ await channel.createObject({ data: { id: 'article-42', title: 'The Meaning of Li
|
|
|
235
264
|
```typescript
|
|
236
265
|
// Fire-and-forget: create and reference without waiting
|
|
237
266
|
const id = RoolClient.generateId();
|
|
238
|
-
channel.createObject({ data: { id,
|
|
267
|
+
channel.createObject({ data: { id, text: '{{expand this idea}}' } });
|
|
239
268
|
channel.updateObject(parentId, { data: { notes: [...existingNotes, id] } }); // Add reference immediately
|
|
240
269
|
```
|
|
241
270
|
|
|
@@ -558,6 +587,19 @@ client.on('userStorageChanged', ({ key, value, source }) => {
|
|
|
558
587
|
});
|
|
559
588
|
```
|
|
560
589
|
|
|
590
|
+
### Apps
|
|
591
|
+
|
|
592
|
+
Publish, manage, and discover apps. See [`@rool-dev/app`](/app/) for building apps.
|
|
593
|
+
|
|
594
|
+
| Method | Description |
|
|
595
|
+
|--------|-------------|
|
|
596
|
+
| `publishApp(appId, options): Promise<PublishedAppInfo>` | Publish or update an app (`options.bundle`: zip with `index.html` and `rool-app.json`) |
|
|
597
|
+
| `unpublishApp(appId): Promise<void>` | Unpublish an app |
|
|
598
|
+
| `listApps(): Promise<PublishedAppInfo[]>` | List your own published apps |
|
|
599
|
+
| `getAppInfo(appId): Promise<PublishedAppInfo \| null>` | Get info for a specific app |
|
|
600
|
+
| `findApps(options?): Promise<PublishedAppInfo[]>` | Search public apps. Options: `query` (semantic search string), `limit` (default 20, max 100). Omit `query` to browse all. |
|
|
601
|
+
| `installApp(spaceId, appId, channelId?): Promise<string>` | Install an app into a space. Creates/updates a channel with the app's manifest settings (name, system instruction, collections). Returns the channel ID. Defaults `channelId` to `appId`. |
|
|
602
|
+
|
|
561
603
|
### Utilities
|
|
562
604
|
|
|
563
605
|
| Method | Description |
|
|
@@ -638,6 +680,7 @@ A channel is a named context within a space. All object operations, AI prompts,
|
|
|
638
680
|
| `userId: string` | Current user's ID |
|
|
639
681
|
| `channelId: string` | Channel ID (read-only, fixed at open time) |
|
|
640
682
|
| `isReadOnly: boolean` | True if viewer role |
|
|
683
|
+
| `appUrl: string \| null` | URL of the installed app, or null if this is a plain channel |
|
|
641
684
|
|
|
642
685
|
### Lifecycle
|
|
643
686
|
|
|
@@ -645,6 +688,7 @@ A channel is a named context within a space. All object operations, AI prompts,
|
|
|
645
688
|
|--------|-------------|
|
|
646
689
|
| `close(): void` | Clean up resources and stop receiving updates |
|
|
647
690
|
| `rename(name): Promise<void>` | Rename this channel |
|
|
691
|
+
| `conversation(conversationId): ConversationHandle` | Get a handle scoped to a specific conversation (see [Conversations](#conversations)) |
|
|
648
692
|
|
|
649
693
|
### Object Operations
|
|
650
694
|
|
|
@@ -680,12 +724,14 @@ Objects are plain key/value records. `id` is the only reserved field; everything
|
|
|
680
724
|
Find objects using structured filters and/or natural language.
|
|
681
725
|
|
|
682
726
|
- **`where` only** — exact-match filtering, no AI, no credits.
|
|
727
|
+
- **`collection` only** — filter by collection name (shape-based matching), no AI, no credits.
|
|
683
728
|
- **`prompt` only** — AI-powered semantic query over all objects.
|
|
684
729
|
- **`where` + `prompt`** — `where` (and `objectIds`) narrow the data set first, then the AI queries within the constrained set.
|
|
685
730
|
|
|
686
731
|
| Option | Description |
|
|
687
732
|
|--------|-------------|
|
|
688
|
-
| `where` | Exact-match field filter (e.g. `{
|
|
733
|
+
| `where` | Exact-match field filter (e.g. `{ status: 'published' }`). Values must match literally — no operators or `{{placeholders}}`. When combined with `prompt`, constrains which objects the AI can see. |
|
|
734
|
+
| `collection` | Filter by collection name. Only returns objects whose shape matches the named collection. |
|
|
689
735
|
| `prompt` | Natural language query. Triggers AI evaluation (uses credits). |
|
|
690
736
|
| `limit` | Maximum number of results. |
|
|
691
737
|
| `objectIds` | Scope to specific object IDs. Constrains the candidate set in both structured and AI queries. |
|
|
@@ -695,9 +741,20 @@ Find objects using structured filters and/or natural language.
|
|
|
695
741
|
**Examples:**
|
|
696
742
|
|
|
697
743
|
```typescript
|
|
744
|
+
// Filter by collection (no AI, no credits)
|
|
745
|
+
const { objects } = await channel.findObjects({
|
|
746
|
+
collection: 'article'
|
|
747
|
+
});
|
|
748
|
+
|
|
698
749
|
// Exact field matching (no AI, no credits)
|
|
699
750
|
const { objects } = await channel.findObjects({
|
|
700
|
-
where: {
|
|
751
|
+
where: { status: 'published' }
|
|
752
|
+
});
|
|
753
|
+
|
|
754
|
+
// Combine collection and field filters
|
|
755
|
+
const { objects } = await channel.findObjects({
|
|
756
|
+
collection: 'article',
|
|
757
|
+
where: { status: 'published' }
|
|
701
758
|
});
|
|
702
759
|
|
|
703
760
|
// Pure natural language query (AI interprets)
|
|
@@ -705,9 +762,9 @@ const { objects, message } = await channel.findObjects({
|
|
|
705
762
|
prompt: 'articles about space exploration published this year'
|
|
706
763
|
});
|
|
707
764
|
|
|
708
|
-
// Combined: where
|
|
765
|
+
// Combined: collection + where narrow the data, prompt queries within it
|
|
709
766
|
const { objects } = await channel.findObjects({
|
|
710
|
-
|
|
767
|
+
collection: 'article',
|
|
711
768
|
prompt: 'that discuss climate solutions positively',
|
|
712
769
|
limit: 10
|
|
713
770
|
});
|
|
@@ -862,9 +919,15 @@ channel.on('objectDeleted', ({ objectId, source }) => void)
|
|
|
862
919
|
// Space metadata
|
|
863
920
|
channel.on('metadataUpdated', ({ metadata, source }) => void)
|
|
864
921
|
|
|
865
|
-
//
|
|
922
|
+
// Collection schema changed
|
|
923
|
+
channel.on('schemaUpdated', ({ schema, source }) => void)
|
|
924
|
+
|
|
925
|
+
// Channel metadata updated (name, appUrl)
|
|
866
926
|
channel.on('channelUpdated', ({ channelId, source }) => void)
|
|
867
927
|
|
|
928
|
+
// Conversation interaction history updated
|
|
929
|
+
channel.on('conversationUpdated', ({ conversationId, channelId, source }) => void)
|
|
930
|
+
|
|
868
931
|
// Full state replacement (undo/redo, resync after error)
|
|
869
932
|
channel.on('reset', ({ source }) => void)
|
|
870
933
|
|
|
@@ -890,99 +953,21 @@ try {
|
|
|
890
953
|
|
|
891
954
|
## Interaction History
|
|
892
955
|
|
|
893
|
-
Each channel
|
|
894
|
-
|
|
895
|
-
### What the AI Receives
|
|
896
|
-
|
|
897
|
-
AI operations (`prompt`, `createObject`, `updateObject`, `findObjects`) automatically receive:
|
|
898
|
-
|
|
899
|
-
- **Interaction history** — Previous interactions and their results from this channel
|
|
900
|
-
- **Recently modified objects** — Objects in the space recently created or changed
|
|
901
|
-
- **Selected objects** — Objects passed via `objectIds` are given primary focus
|
|
902
|
-
|
|
903
|
-
This context flows automatically — no configuration needed. The AI sees enough history to maintain coherent interactions while respecting the `_`-prefixed field hiding rules.
|
|
904
|
-
|
|
905
|
-
### Accessing History
|
|
906
|
-
|
|
907
|
-
```typescript
|
|
908
|
-
// Get interactions for this channel
|
|
909
|
-
const interactions = channel.getInteractions();
|
|
910
|
-
// Returns: Interaction[]
|
|
911
|
-
```
|
|
956
|
+
Each channel contains one or more conversations, each with its own interaction history. History is stored in the space data and syncs in real-time. Truncated to the most recent 50 entries per conversation.
|
|
912
957
|
|
|
913
|
-
###
|
|
958
|
+
### Conversation History Methods
|
|
914
959
|
|
|
915
960
|
| Method | Description |
|
|
916
961
|
|--------|-------------|
|
|
917
|
-
| `getInteractions(): Interaction[]` | Get interactions for
|
|
918
|
-
| `getSystemInstruction(): string \| undefined` | Get system instruction for
|
|
919
|
-
| `setSystemInstruction(instruction): Promise<void>` | Set system instruction for
|
|
962
|
+
| `getInteractions(): Interaction[]` | Get interactions for the default conversation |
|
|
963
|
+
| `getSystemInstruction(): string \| undefined` | Get system instruction for the default conversation |
|
|
964
|
+
| `setSystemInstruction(instruction): Promise<void>` | Set system instruction for the default conversation. Pass `null` to clear. |
|
|
965
|
+
| `getConversations(): ConversationInfo[]` | List all conversations in this channel |
|
|
966
|
+
| `deleteConversation(conversationId): Promise<void>` | Delete a conversation (cannot delete `'default'`) |
|
|
967
|
+
| `renameConversation(name): Promise<void>` | Rename the default conversation |
|
|
920
968
|
|
|
921
969
|
Channel management (listing, renaming, deleting channels) is done via the client — see [Channel Management](#channel-management).
|
|
922
970
|
|
|
923
|
-
### System Instructions
|
|
924
|
-
|
|
925
|
-
System instructions customize how the AI behaves within a channel. The instruction persists across all prompts in that channel.
|
|
926
|
-
|
|
927
|
-
```typescript
|
|
928
|
-
// Make the AI behave like an SQL interpreter
|
|
929
|
-
await channel.setSystemInstruction(
|
|
930
|
-
'Behave like an intelligent SQL interpreter. Respond with simple markdown tables. ' +
|
|
931
|
-
'Translate the objects in the space to the implied structure in your responses.'
|
|
932
|
-
);
|
|
933
|
-
|
|
934
|
-
// Now prompts are interpreted as SQL-like queries
|
|
935
|
-
const { message } = await channel.prompt('SELECT task, due_date FROM tasks ORDER BY due_date');
|
|
936
|
-
// Returns a markdown table of tasks, even if no "tasks" objects exist -
|
|
937
|
-
// the AI infers actual tasks from the space content
|
|
938
|
-
|
|
939
|
-
// Clear the instruction to return to default behavior
|
|
940
|
-
await channel.setSystemInstruction(null);
|
|
941
|
-
```
|
|
942
|
-
|
|
943
|
-
System instructions are useful for:
|
|
944
|
-
- Defining response formats (tables, JSON, specific templates)
|
|
945
|
-
- Setting a persona or expertise area
|
|
946
|
-
- Constraining the AI to specific operations
|
|
947
|
-
- Creating domain-specific interfaces over your space data
|
|
948
|
-
|
|
949
|
-
### Listening for Updates
|
|
950
|
-
|
|
951
|
-
```typescript
|
|
952
|
-
channel.on('channelUpdated', ({ channelId, source }) => {
|
|
953
|
-
// Channel updated - refresh if needed
|
|
954
|
-
const interactions = channel.getInteractions();
|
|
955
|
-
renderInteractions(interactions);
|
|
956
|
-
});
|
|
957
|
-
```
|
|
958
|
-
|
|
959
|
-
### Multiple Channels
|
|
960
|
-
|
|
961
|
-
Each channel has its own interaction history. To work with multiple independent histories on the same space, open multiple channels:
|
|
962
|
-
|
|
963
|
-
```typescript
|
|
964
|
-
// Open two channels on the same space
|
|
965
|
-
const research = await client.openChannel('space-id', 'research');
|
|
966
|
-
const main = await client.openChannel('space-id', 'main');
|
|
967
|
-
|
|
968
|
-
// Each has independent history
|
|
969
|
-
await research.prompt("Analyze this data");
|
|
970
|
-
await main.prompt("Summarize findings");
|
|
971
|
-
|
|
972
|
-
// Close when done
|
|
973
|
-
research.close();
|
|
974
|
-
main.close();
|
|
975
|
-
```
|
|
976
|
-
|
|
977
|
-
**Use cases:**
|
|
978
|
-
- **Chat app with sidebar** — Each sidebar entry is a channel with a different channelId
|
|
979
|
-
- **Page refresh** — Store the channelId in localStorage to resume the same channel
|
|
980
|
-
- **Collaborative channels** — Share a channelId between users to enable shared AI interaction history
|
|
981
|
-
|
|
982
|
-
**Tip:** Use the user's id as channelId to share context across tabs/devices, or a fixed string like `'shared'` to share context across all users.
|
|
983
|
-
|
|
984
|
-
Note: Interaction history is truncated to the most recent 50 entries to manage space size.
|
|
985
|
-
|
|
986
971
|
### The ai Field
|
|
987
972
|
|
|
988
973
|
The `ai` field in interactions distinguishes AI-generated responses from synthetic confirmations:
|
|
@@ -991,7 +976,7 @@ The `ai` field in interactions distinguishes AI-generated responses from synthet
|
|
|
991
976
|
|
|
992
977
|
### Tool Calls
|
|
993
978
|
|
|
994
|
-
The `toolCalls` array captures what the AI agent did during execution.
|
|
979
|
+
The `toolCalls` array captures what the AI agent did during execution. The `conversationUpdated` event fires when each tool starts and completes. A tool call without a `result` is still running; once `result` is present, the tool has finished.
|
|
995
980
|
|
|
996
981
|
## Data Types
|
|
997
982
|
|
|
@@ -1042,17 +1027,36 @@ interface RoolObjectStat {
|
|
|
1042
1027
|
}
|
|
1043
1028
|
```
|
|
1044
1029
|
|
|
1045
|
-
### Channels
|
|
1030
|
+
### Channels and Conversations
|
|
1046
1031
|
|
|
1047
1032
|
```typescript
|
|
1048
|
-
//
|
|
1033
|
+
// Conversation — holds interaction history and optional system instruction
|
|
1034
|
+
interface Conversation {
|
|
1035
|
+
name?: string; // Conversation name (optional)
|
|
1036
|
+
systemInstruction?: string; // Custom system instruction for AI
|
|
1037
|
+
createdAt: number; // Timestamp when conversation was created
|
|
1038
|
+
createdBy: string; // User ID who created the conversation
|
|
1039
|
+
interactions: Interaction[]; // Interaction history
|
|
1040
|
+
}
|
|
1041
|
+
|
|
1042
|
+
// Conversation summary info (returned by channel.getConversations())
|
|
1043
|
+
interface ConversationInfo {
|
|
1044
|
+
id: string;
|
|
1045
|
+
name: string | null;
|
|
1046
|
+
systemInstruction: string | null;
|
|
1047
|
+
createdAt: number;
|
|
1048
|
+
createdBy: string;
|
|
1049
|
+
interactionCount: number;
|
|
1050
|
+
}
|
|
1051
|
+
|
|
1052
|
+
// Channel container with metadata and conversations
|
|
1049
1053
|
interface Channel {
|
|
1050
1054
|
name?: string; // Channel name (optional)
|
|
1051
1055
|
createdAt: number; // Timestamp when channel was created
|
|
1052
1056
|
createdBy: string; // User ID who created the channel
|
|
1053
1057
|
createdByName?: string; // Display name at time of creation
|
|
1054
|
-
|
|
1055
|
-
|
|
1058
|
+
appUrl?: string; // URL of installed app (set by installApp)
|
|
1059
|
+
conversations: Record<string, Conversation>; // Keyed by conversation ID
|
|
1056
1060
|
}
|
|
1057
1061
|
|
|
1058
1062
|
// Channel summary info (returned by client.getChannels)
|
|
@@ -1063,6 +1067,7 @@ interface ChannelInfo {
|
|
|
1063
1067
|
createdBy: string;
|
|
1064
1068
|
createdByName: string | null;
|
|
1065
1069
|
interactionCount: number;
|
|
1070
|
+
appUrl: string | null; // URL of installed app, or null
|
|
1066
1071
|
}
|
|
1067
1072
|
```
|
|
1068
1073
|
|
|
@@ -1074,9 +1079,11 @@ Note: `Channel` and `ChannelInfo` are data types describing the stored channel m
|
|
|
1074
1079
|
interface ToolCall {
|
|
1075
1080
|
name: string; // Tool name (e.g., "create_object", "update_object", "search_web")
|
|
1076
1081
|
input: unknown; // Arguments passed to the tool
|
|
1077
|
-
result
|
|
1082
|
+
result?: string; // Truncated result (absent while tool is running)
|
|
1078
1083
|
}
|
|
1079
1084
|
|
|
1085
|
+
type InteractionStatus = 'pending' | 'streaming' | 'done' | 'error';
|
|
1086
|
+
|
|
1080
1087
|
interface Interaction {
|
|
1081
1088
|
id: string; // Unique ID for this interaction
|
|
1082
1089
|
timestamp: number;
|
|
@@ -1084,7 +1091,8 @@ interface Interaction {
|
|
|
1084
1091
|
userName?: string | null; // Display name at time of interaction
|
|
1085
1092
|
operation: 'prompt' | 'createObject' | 'updateObject' | 'deleteObjects';
|
|
1086
1093
|
input: string; // What the user did: prompt text or action description
|
|
1087
|
-
output: string | null; //
|
|
1094
|
+
output: string | null; // AI response or confirmation message (may be partial when streaming)
|
|
1095
|
+
status: InteractionStatus; // Lifecycle status (pending → streaming → done/error)
|
|
1088
1096
|
ai: boolean; // Whether AI was invoked (vs synthetic confirmation)
|
|
1089
1097
|
modifiedObjectIds: string[]; // Objects affected by this interaction
|
|
1090
1098
|
toolCalls: ToolCall[]; // Tools called during this interaction (for AI prompts)
|
|
@@ -1122,58 +1130,6 @@ interface PromptOptions {
|
|
|
1122
1130
|
}
|
|
1123
1131
|
```
|
|
1124
1132
|
|
|
1125
|
-
## Patterns & Examples
|
|
1126
|
-
|
|
1127
|
-
A Rool Space is a persistent, shared world model. Applications project different interaction patterns onto the same core primitives:
|
|
1128
|
-
|
|
1129
|
-
- **Objects** store durable state, with references to other objects via data fields
|
|
1130
|
-
- **Channels** provide independent AI interaction contexts over shared objects
|
|
1131
|
-
- **Events** describe what changed in real-time
|
|
1132
|
-
|
|
1133
|
-
Below are a few representative patterns.
|
|
1134
|
-
|
|
1135
|
-
### Chat With Generated Artifacts
|
|
1136
|
-
|
|
1137
|
-
- **Space**: documents, notes, images, tasks as objects
|
|
1138
|
-
- **Channels**: each chat thread is a separate channel on the same space
|
|
1139
|
-
- **UI**: renders interactions from `getInteractions()` as chat; derives artifact lists from object events
|
|
1140
|
-
|
|
1141
|
-
**Pattern**
|
|
1142
|
-
- Interaction history syncs in real-time; UI renders entries as chat bubbles
|
|
1143
|
-
- Artifacts are persistent objects shared across all channels
|
|
1144
|
-
- Listen to `channelUpdated` event to update chat UI
|
|
1145
|
-
- Selecting objects defines the AI working set via `objectIds`
|
|
1146
|
-
|
|
1147
|
-
### Multi-User World / Text Adventure
|
|
1148
|
-
|
|
1149
|
-
- **Space**: rooms, items, NPCs, players as objects
|
|
1150
|
-
- **References**: navigation, containment, location via data fields
|
|
1151
|
-
- **Channel**: player commands and narrative continuity
|
|
1152
|
-
|
|
1153
|
-
**Pattern**
|
|
1154
|
-
- The space is the shared world state
|
|
1155
|
-
- Objects can be created dynamically as the world expands
|
|
1156
|
-
- AI generates descriptions and events using `{{placeholders}}`
|
|
1157
|
-
|
|
1158
|
-
### Collaborative Knowledge Graph
|
|
1159
|
-
|
|
1160
|
-
- **Space**: concepts, sources, hypotheses as objects
|
|
1161
|
-
- **References**: semantic connections between objects via data fields
|
|
1162
|
-
- **Channel**: exploratory analysis and questioning
|
|
1163
|
-
|
|
1164
|
-
**Pattern**
|
|
1165
|
-
- Graph structure lives in object data fields containing other object IDs
|
|
1166
|
-
- AI operates on selected subgraphs via `objectIds`
|
|
1167
|
-
- Analysis results are stored; reasoning steps are transient
|
|
1168
|
-
|
|
1169
|
-
### Common Design Invariants
|
|
1170
|
-
|
|
1171
|
-
- Durable content lives in space objects
|
|
1172
|
-
- References between objects are data fields whose values are object IDs
|
|
1173
|
-
- Interaction history lives in channels (persistent, synced, truncated to 50 entries)
|
|
1174
|
-
- UI state lives in the client, space metadata, or `_`-prefixed fields
|
|
1175
|
-
- AI focus is controlled by object selection, not by replaying history
|
|
1176
|
-
|
|
1177
1133
|
## License
|
|
1178
1134
|
|
|
1179
1135
|
MIT - see [LICENSE](../../LICENSE) for details.
|
package/dist/apps.d.ts
CHANGED
|
@@ -18,7 +18,7 @@ export declare class AppsClient {
|
|
|
18
18
|
/**
|
|
19
19
|
* Publish or update an app.
|
|
20
20
|
* @param appId - URL-safe identifier for the app
|
|
21
|
-
* @param options -
|
|
21
|
+
* @param options - Bundle zip file (must include index.html and rool-app.json)
|
|
22
22
|
*/
|
|
23
23
|
publish(appId: string, options: PublishAppOptions): Promise<PublishedAppInfo>;
|
|
24
24
|
/**
|
package/dist/apps.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAmB;gBAErB,MAAM,EAAE,gBAAgB;IAIpC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAkBzC;;OAEG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAsB1D;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;
|
|
1
|
+
{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAmB;gBAErB,MAAM,EAAE,gBAAgB;IAIpC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAkBzC;;OAEG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAsB1D;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwBnF;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAe9C"}
|
package/dist/apps.js
CHANGED
|
@@ -47,7 +47,7 @@ export class AppsClient {
|
|
|
47
47
|
/**
|
|
48
48
|
* Publish or update an app.
|
|
49
49
|
* @param appId - URL-safe identifier for the app
|
|
50
|
-
* @param options -
|
|
50
|
+
* @param options - Bundle zip file (must include index.html and rool-app.json)
|
|
51
51
|
*/
|
|
52
52
|
async publish(appId, options) {
|
|
53
53
|
const tokens = await this.config.authManager.getTokens();
|
|
@@ -56,10 +56,6 @@ export class AppsClient {
|
|
|
56
56
|
const headers = { Authorization: `Bearer ${tokens.accessToken}`, 'X-Rool-Token': tokens.roolToken };
|
|
57
57
|
const formData = new FormData();
|
|
58
58
|
formData.append('bundle', options.bundle);
|
|
59
|
-
formData.append('name', options.name);
|
|
60
|
-
if (options.spa !== undefined) {
|
|
61
|
-
formData.append('spa', String(options.spa));
|
|
62
|
-
}
|
|
63
59
|
const response = await fetch(`${this.config.appsUrl}/${encodeURIComponent(appId)}`, {
|
|
64
60
|
method: 'POST',
|
|
65
61
|
headers,
|
package/dist/apps.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"apps.js","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,cAAc;AACd,2DAA2D;AAC3D,gFAAgF;AAUhF,MAAM,OAAO,UAAU;IACb,MAAM,CAAmB;IAEjC,YAAY,MAAwB;QAClC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;QACzD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAElD,MAAM,OAAO,GAA2B,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,WAAW,EAAE,EAAE,cAAc,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QAE5H,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE;YAChD,MAAM,EAAE,KAAK;YACb,OAAO;SACR,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,wBAAwB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;QACpF,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG,CAAC,KAAa;QACrB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;QACzD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAElD,MAAM,OAAO,GAA2B,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,WAAW,EAAE,EAAE,cAAc,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QAE5H,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,EAAE;YAClF,MAAM,EAAE,KAAK;YACb,OAAO;SACR,CAAC,CAAC;QAEH,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,sBAAsB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;QAClF,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,KAAa,EAAE,OAA0B;QACrD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;QACzD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QAElD,MAAM,OAAO,GAA2B,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,WAAW,EAAE,EAAE,cAAc,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QAE5H,MAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;QAChC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;
|
|
1
|
+
{"version":3,"file":"apps.js","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"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"}
|