@rool-dev/sdk 0.3.1-dev.fa375c5 → 0.3.2-dev.1f10ef1

package/README.md

@@ -4,18 +4,14 @@ The TypeScript SDK for Rool, a persistent and collaborative environment for orga
 
 > **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.
 
-Rool enables you to build applications where AI operates on a structured world model rather than a text conversation. The context for all AI operations is the full object graph, allowing the system to reason about, update, and expand the state of your application directly.
+The SDK manages authentication, real-time synchronization, and media storage. Core primitives:
 
-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.
-
-**Core primitives:**
 - **Spaces** — Containers for objects, schema, metadata, and channels
-- **Channels** — Named contexts within a space, each with independent interaction history. All object and AI operations go through a channel.
+- **Channels** — Named contexts within a space. All object and AI operations go through a channel.
+- **Conversations** — Independent interaction histories within a channel.
 - **Objects** — Key-value records with any fields you define. References between objects are data fields whose values are object IDs.
 - **AI operations** — Create, update, or query objects using natural language and `{{placeholders}}`
 
-See [Patterns & Examples](#patterns--examples) for what you can build.
-
 ## Installation
 
 ```bash
@@ -84,7 +80,7 @@ channel.close();
 
 ### Spaces and Channels
 
-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 has its own interaction history.
+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.
 
 There are two main handles:
 - **`RoolSpace`** — Lightweight admin handle for user management, link access, channel management, and export. No real-time subscription.
@@ -111,6 +107,40 @@ The `channelId` is fixed when you open a channel and cannot be changed. To use a
 - 1–32 characters
 - Only alphanumeric characters, hyphens (`-`), and underscores (`_`)
 
+### Conversations
+
+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.
+
+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:
+
+```typescript
+// Default conversation — most apps use this
+const channel = await client.openChannel('space-id', 'main');
+await channel.prompt('Hello');  // Uses 'default' conversation
+
+// Conversation handle — for multi-thread UIs
+const thread = channel.conversation('thread-42');
+await thread.prompt('Hello');  // Uses 'thread-42' conversation
+thread.getInteractions();      // Interactions for thread-42 only
+```
+
+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.
+
+```typescript
+// System instructions are per-conversation
+const thread = channel.conversation('research');
+await thread.setSystemInstruction('Respond in haiku');
+
+// List all conversations in this channel
+const conversations = channel.getConversations();
+
+// Delete a conversation (cannot delete 'default')
+await channel.deleteConversation('old-thread');
+
+// Rename a conversation
+await thread.rename('Research Thread');
+```
+
 ### Objects & References
 
 **Objects** are plain key-value records. The `id` field is reserved; everything else is application-defined.
@@ -557,6 +587,19 @@ client.on('userStorageChanged', ({ key, value, source }) => {
 });
 ```
 
+### Apps
+
+Publish, manage, and discover apps. See [`@rool-dev/app`](/app/) for building apps.
+
+| Method | Description |
+|--------|-------------|
+| `publishApp(appId, options): Promise<PublishedAppInfo>` | Publish or update an app (`options.bundle`: zip with `index.html` and `rool-app.json`) |
+| `unpublishApp(appId): Promise<void>` | Unpublish an app |
+| `listApps(): Promise<PublishedAppInfo[]>` | List your own published apps |
+| `getAppInfo(appId): Promise<PublishedAppInfo \| null>` | Get info for a specific app |
+| `findApps(options?): Promise<PublishedAppInfo[]>` | Search public apps. Options: `query` (semantic search string), `limit` (default 20, max 100). Omit `query` to browse all. |
+| `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`. |
+
 ### Utilities
 
 | Method | Description |
@@ -637,6 +680,7 @@ A channel is a named context within a space. All object operations, AI prompts,
 | `userId: string` | Current user's ID |
 | `channelId: string` | Channel ID (read-only, fixed at open time) |
 | `isReadOnly: boolean` | True if viewer role |
+| `appUrl: string \| null` | URL of the installed app, or null if this is a plain channel |
 
 ### Lifecycle
 
@@ -644,6 +688,7 @@ A channel is a named context within a space. All object operations, AI prompts,
 |--------|-------------|
 | `close(): void` | Clean up resources and stop receiving updates |
 | `rename(name): Promise<void>` | Rename this channel |
+| `conversation(conversationId): ConversationHandle` | Get a handle scoped to a specific conversation (see [Conversations](#conversations)) |
 
 ### Object Operations
 
@@ -877,9 +922,12 @@ channel.on('metadataUpdated', ({ metadata, source }) => void)
 // Collection schema changed
 channel.on('schemaUpdated', ({ schema, source }) => void)
 
-// Channel updated (fetch with getInteractions())
+// Channel metadata updated (name, appUrl)
 channel.on('channelUpdated', ({ channelId, source }) => void)
 
+// Conversation interaction history updated
+channel.on('conversationUpdated', ({ conversationId, channelId, source }) => void)
+
 // Full state replacement (undo/redo, resync after error)
 channel.on('reset', ({ source }) => void)
 
@@ -905,99 +953,21 @@ try {
 
 ## Interaction History
 
-Each channel has a `channelId` that identifies it. The history records all meaningful interactions (prompts, object mutations) as self-contained entries, each capturing the request and its result. History is stored in the space data itself and syncs in real-time to all clients.
+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.
 
-### What the AI Receives
-
-AI operations (`prompt`, `createObject`, `updateObject`, `findObjects`) automatically receive:
-
-- **Interaction history** — Previous interactions and their results from this channel
-- **Recently modified objects** — Objects in the space recently created or changed
-- **Selected objects** — Objects passed via `objectIds` are given primary focus
-
-This context flows automatically — no configuration needed. The AI sees enough history to maintain coherent interactions while respecting the `_`-prefixed field hiding rules.
-
-### Accessing History
-
-```typescript
-// Get interactions for this channel
-const interactions = channel.getInteractions();
-// Returns: Interaction[]
-```
-
-### Channel History Methods
+### Conversation History Methods
 
 | Method | Description |
 |--------|-------------|
-| `getInteractions(): Interaction[]` | Get interactions for this channel |
-| `getSystemInstruction(): string \| undefined` | Get system instruction for this channel |
-| `setSystemInstruction(instruction): Promise<void>` | Set system instruction for this channel. Pass `null` to clear. |
+| `getInteractions(): Interaction[]` | Get interactions for the default conversation |
+| `getSystemInstruction(): string \| undefined` | Get system instruction for the default conversation |
+| `setSystemInstruction(instruction): Promise<void>` | Set system instruction for the default conversation. Pass `null` to clear. |
+| `getConversations(): ConversationInfo[]` | List all conversations in this channel |
+| `deleteConversation(conversationId): Promise<void>` | Delete a conversation (cannot delete `'default'`) |
+| `renameConversation(name): Promise<void>` | Rename the default conversation |
 
 Channel management (listing, renaming, deleting channels) is done via the client — see [Channel Management](#channel-management).
 
-### System Instructions
-
-System instructions customize how the AI behaves within a channel. The instruction persists across all prompts in that channel.
-
-```typescript
-// Make the AI behave like an SQL interpreter
-await channel.setSystemInstruction(
-  'Behave like an intelligent SQL interpreter. Respond with simple markdown tables. ' +
-  'Translate the objects in the space to the implied structure in your responses.'
-);
-
-// Now prompts are interpreted as SQL-like queries
-const { message } = await channel.prompt('SELECT task, due_date FROM tasks ORDER BY due_date');
-// Returns a markdown table of tasks, even if no "tasks" objects exist -
-// the AI infers actual tasks from the space content
-
-// Clear the instruction to return to default behavior
-await channel.setSystemInstruction(null);
-```
-
-System instructions are useful for:
-- Defining response formats (tables, JSON, specific templates)
-- Setting a persona or expertise area
-- Constraining the AI to specific operations
-- Creating domain-specific interfaces over your space data
-
-### Listening for Updates
-
-```typescript
-channel.on('channelUpdated', ({ channelId, source }) => {
-  // Channel updated - refresh if needed
-  const interactions = channel.getInteractions();
-  renderInteractions(interactions);
-});
-```
-
-### Multiple Channels
-
-Each channel has its own interaction history. To work with multiple independent histories on the same space, open multiple channels:
-
-```typescript
-// Open two channels on the same space
-const research = await client.openChannel('space-id', 'research');
-const main = await client.openChannel('space-id', 'main');
-
-// Each has independent history
-await research.prompt("Analyze this data");
-await main.prompt("Summarize findings");
-
-// Close when done
-research.close();
-main.close();
-```
-
-**Use cases:**
-- **Chat app with sidebar** — Each sidebar entry is a channel with a different channelId
-- **Page refresh** — Store the channelId in localStorage to resume the same channel
-- **Collaborative channels** — Share a channelId between users to enable shared AI interaction history
-
-**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.
-
-Note: Interaction history is truncated to the most recent 50 entries to manage space size.
-
 ### The ai Field
 
 The `ai` field in interactions distinguishes AI-generated responses from synthetic confirmations:
@@ -1006,7 +976,7 @@ The `ai` field in interactions distinguishes AI-generated responses from synthet
 
 ### Tool Calls
 
-The `toolCalls` array captures what the AI agent did during execution. Use it to build responsive UIs that show progress while the agent works — the `channelUpdated` event fires as each tool completes, letting you display status updates or hints in real-time.
+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.
 
 ## Data Types
 
@@ -1057,17 +1027,36 @@ interface RoolObjectStat {
 }
 ```
 
-### Channels
+### Channels and Conversations
 
 ```typescript
-// Channel container with metadata
+// Conversation — holds interaction history and optional system instruction
+interface Conversation {
+  name?: string;                  // Conversation name (optional)
+  systemInstruction?: string;     // Custom system instruction for AI
+  createdAt: number;              // Timestamp when conversation was created
+  createdBy: string;              // User ID who created the conversation
+  interactions: Interaction[];    // Interaction history
+}
+
+// Conversation summary info (returned by channel.getConversations())
+interface ConversationInfo {
+  id: string;
+  name: string | null;
+  systemInstruction: string | null;
+  createdAt: number;
+  createdBy: string;
+  interactionCount: number;
+}
+
+// Channel container with metadata and conversations
 interface Channel {
   name?: string;                // Channel name (optional)
   createdAt: number;            // Timestamp when channel was created
   createdBy: string;            // User ID who created the channel
   createdByName?: string;       // Display name at time of creation
-  systemInstruction?: string;   // Custom system instruction for AI
-  interactions: Interaction[];  // Interaction history
+  appUrl?: string;              // URL of installed app (set by installApp)
+  conversations: Record<string, Conversation>;  // Keyed by conversation ID
 }
 
 // Channel summary info (returned by client.getChannels)
@@ -1078,6 +1067,7 @@ interface ChannelInfo {
   createdBy: string;
   createdByName: string | null;
   interactionCount: number;
+  appUrl: string | null;        // URL of installed app, or null
 }
 ```
 
@@ -1089,9 +1079,11 @@ Note: `Channel` and `ChannelInfo` are data types describing the stored channel m
 interface ToolCall {
   name: string;      // Tool name (e.g., "create_object", "update_object", "search_web")
   input: unknown;    // Arguments passed to the tool
-  result: string;    // Truncated result (max 500 chars)
+  result?: string;   // Truncated result (absent while tool is running)
 }
 
+type InteractionStatus = 'pending' | 'streaming' | 'done' | 'error';
+
 interface Interaction {
   id: string;                    // Unique ID for this interaction
   timestamp: number;
@@ -1099,7 +1091,8 @@ interface Interaction {
   userName?: string | null;      // Display name at time of interaction
   operation: 'prompt' | 'createObject' | 'updateObject' | 'deleteObjects';
   input: string;                 // What the user did: prompt text or action description
-  output: string | null;         // Result: AI response or confirmation message (null while in-progress)
+  output: string | null;         // AI response or confirmation message (may be partial when streaming)
+  status: InteractionStatus;     // Lifecycle status (pending → streaming → done/error)
   ai: boolean;                   // Whether AI was invoked (vs synthetic confirmation)
   modifiedObjectIds: string[];   // Objects affected by this interaction
   toolCalls: ToolCall[];         // Tools called during this interaction (for AI prompts)
@@ -1137,58 +1130,6 @@ interface PromptOptions {
 }
 ```
 
-## Patterns & Examples
-
-A Rool Space is a persistent, shared world model. Applications project different interaction patterns onto the same core primitives:
-
-- **Objects** store durable state, with references to other objects via data fields
-- **Channels** provide independent AI interaction contexts over shared objects
-- **Events** describe what changed in real-time
-
-Below are a few representative patterns.
-
-### Chat With Generated Artifacts
-
-- **Space**: documents, notes, images, tasks as objects
-- **Channels**: each chat thread is a separate channel on the same space
-- **UI**: renders interactions from `getInteractions()` as chat; derives artifact lists from object events
-
-**Pattern**
-- Interaction history syncs in real-time; UI renders entries as chat bubbles
-- Artifacts are persistent objects shared across all channels
-- Listen to `channelUpdated` event to update chat UI
-- Selecting objects defines the AI working set via `objectIds`
-
-### Multi-User World / Text Adventure
-
-- **Space**: rooms, items, NPCs, players as objects
-- **References**: navigation, containment, location via data fields
-- **Channel**: player commands and narrative continuity
-
-**Pattern**
-- The space is the shared world state
-- Objects can be created dynamically as the world expands
-- AI generates descriptions and events using `{{placeholders}}`
-
-### Collaborative Knowledge Graph
-
-- **Space**: concepts, sources, hypotheses as objects
-- **References**: semantic connections between objects via data fields
-- **Channel**: exploratory analysis and questioning
-
-**Pattern**
-- Graph structure lives in object data fields containing other object IDs
-- AI operates on selected subgraphs via `objectIds`
-- Analysis results are stored; reasoning steps are transient
-
-### Common Design Invariants
-
-- Durable content lives in space objects
-- References between objects are data fields whose values are object IDs
-- Interaction history lives in channels (persistent, synced, truncated to 50 entries)
-- UI state lives in the client, space metadata, or `_`-prefixed fields
-- AI focus is controlled by object selection, not by replaying history
-
 ## License
 
 MIT - see [LICENSE](../../LICENSE) for details.

package/dist/apps.d.ts

@@ -18,7 +18,7 @@ export declare class AppsClient {
     /**
      * Publish or update an app.
      * @param appId - URL-safe identifier for the app
-     * @param options - App name, bundle (zip file), and optional SPA flag
+     * @param options - Bundle zip file (must include index.html and rool-app.json)
      */
     publish(appId: string, options: PublishAppOptions): Promise<PublishedAppInfo>;
     /**

package/dist/apps.d.ts.map

@@ -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;IA4BnF;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAe9C"}
+{"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

@@ -47,7 +47,7 @@ export class AppsClient {
     /**
      * Publish or update an app.
      * @param appId - URL-safe identifier for the app
-     * @param options - App name, bundle (zip file), and optional SPA flag
+     * @param options - Bundle zip file (must include index.html and rool-app.json)
      */
     async publish(appId, options) {
         const tokens = await this.config.authManager.getTokens();
@@ -56,10 +56,6 @@ export class AppsClient {
         const headers = { Authorization: `Bearer ${tokens.accessToken}`, 'X-Rool-Token': tokens.roolToken };
         const formData = new FormData();
         formData.append('bundle', options.bundle);
-        formData.append('name', options.name);
-        if (options.spa !== undefined) {
-            formData.append('spa', String(options.spa));
-        }
         const response = await fetch(`${this.config.appsUrl}/${encodeURIComponent(appId)}`, {
             method: 'POST',
             headers,

package/dist/apps.js.map

@@ -1 +1 @@
-{"version":3,"file":"apps.js","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"apps.js","sourceRoot":"","sources":["../src/apps.ts"],"names":[],"mappings":"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"}

package/dist/channel.d.ts

@@ -3,7 +3,7 @@ import type { GraphQLClient } from './graphql.js';
 import type { MediaClient } from './media.js';
 import type { AuthManager } from './auth.js';
 import type { Logger } from './logger.js';
-import type { RoolObject, RoolObjectStat, ChannelEvents, RoolUserRole, PromptOptions, FindObjectsOptions, CreateObjectOptions, UpdateObjectOptions, MediaInfo, MediaResponse, Interaction, Channel, LinkAccess, SpaceSchema, CollectionDef, FieldDef } from './types.js';
+import type { RoolObject, RoolObjectStat, ChannelEvents, RoolUserRole, PromptOptions, FindObjectsOptions, CreateObjectOptions, UpdateObjectOptions, MediaInfo, MediaResponse, Interaction, Channel, ConversationInfo, LinkAccess, SpaceSchema, CollectionDef, FieldDef } from './types.js';
 export declare function generateEntityId(): string;
 export interface ChannelConfig {
     id: string;
@@ -56,6 +56,7 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
     private _linkAccess;
     private _userId;
     private _channelId;
+    private _conversationId;
     private _closed;
     private graphqlClient;
     private mediaClient;
@@ -94,11 +95,40 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
      * Fixed at open time — cannot be changed.
      */
     get channelId(): string;
+    /**
+     * Get the conversation ID for this channel.
+     * Defaults to 'default' for most apps.
+     */
+    get conversationId(): string;
     get isReadOnly(): boolean;
     /**
-     * Get interactions for this channel.
+     * Get the app URL if this channel was created via installApp, or null.
+     */
+    get appUrl(): string | null;
+    /**
+     * Get interactions for the current conversation.
      */
     getInteractions(): Interaction[];
+    /** @internal */
+    _getInteractionsImpl(conversationId: string): Interaction[];
+    /**
+     * Get all conversations in this channel.
+     * Returns summary info (no full interaction data) for each conversation.
+     */
+    getConversations(): ConversationInfo[];
+    /**
+     * Delete a conversation from this channel.
+     * Cannot delete the conversation you are currently using.
+     */
+    deleteConversation(conversationId: string): Promise<void>;
+    /**
+     * Get a handle for a specific conversation within this channel.
+     * The handle scopes AI and mutation operations to that conversation's
+     * interaction history, while sharing the channel's single SSE connection.
+     *
+     * Conversations are auto-created on first interaction — no explicit create needed.
+     */
+    conversation(conversationId: string): ConversationHandle;
     /**
      * Close this channel and clean up resources.
      * Stops real-time subscription and unregisters from client.
@@ -162,6 +192,11 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
         objects: RoolObject[];
         message: string;
     }>;
+    /** @internal */
+    _findObjectsImpl(options: FindObjectsOptions, conversationId: string): Promise<{
+        objects: RoolObject[];
+        message: string;
+    }>;
     /**
      * Get all object IDs (sync, from local cache).
      * The list is loaded on open and kept current via SSE events.
@@ -182,6 +217,11 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
         object: RoolObject;
         message: string;
     }>;
+    /** @internal */
+    _createObjectImpl(options: CreateObjectOptions, conversationId: string): Promise<{
+        object: RoolObject;
+        message: string;
+    }>;
     /**
      * Update an existing object.
      * @param objectId - The ID of the object to update
@@ -194,11 +234,18 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
         object: RoolObject;
         message: string;
     }>;
+    /** @internal */
+    _updateObjectImpl(objectId: string, options: UpdateObjectOptions, conversationId: string): Promise<{
+        object: RoolObject;
+        message: string;
+    }>;
     /**
      * Delete objects by IDs.
      * Other objects that reference deleted objects via data fields will retain stale ref values.
      */
     deleteObjects(objectIds: string[]): Promise<void>;
+    /** @internal */
+    _deleteObjectsImpl(objectIds: string[], conversationId: string): Promise<void>;
     /**
      * Get the current schema for this space.
      * Returns a map of collection names to their definitions.
@@ -211,6 +258,8 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
      * @returns The created CollectionDef
      */
     createCollection(name: string, fields: FieldDef[]): Promise<CollectionDef>;
+    /** @internal */
+    _createCollectionImpl(name: string, fields: FieldDef[], conversationId: string): Promise<CollectionDef>;
     /**
      * Alter an existing collection schema, replacing its field definitions.
      * @param name - Name of the collection to alter
@@ -218,26 +267,47 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
      * @returns The updated CollectionDef
      */
     alterCollection(name: string, fields: FieldDef[]): Promise<CollectionDef>;
+    /** @internal */
+    _alterCollectionImpl(name: string, fields: FieldDef[], conversationId: string): Promise<CollectionDef>;
     /**
      * Drop a collection schema.
      * @param name - Name of the collection to drop
      */
     dropCollection(name: string): Promise<void>;
+    /** @internal */
+    _dropCollectionImpl(name: string, conversationId: string): Promise<void>;
     /**
-     * Get the system instruction for this channel.
+     * Get the system instruction for the current conversation.
      * Returns undefined if no system instruction is set.
      */
     getSystemInstruction(): string | undefined;
+    /** @internal */
+    _getSystemInstructionImpl(conversationId: string): string | undefined;
     /**
-     * Set the system instruction for this channel.
+     * Set the system instruction for the current conversation.
      * Pass null to clear the instruction.
      */
     setSystemInstruction(instruction: string | null): Promise<void>;
+    /** @internal */
+    _setSystemInstructionImpl(instruction: string | null, conversationId: string): Promise<void>;
+    /**
+     * Rename the current conversation.
+     */
+    renameConversation(name: string): Promise<void>;
+    /** @internal */
+    _renameConversationImpl(name: string, conversationId: string): Promise<void>;
+    /**
+     * Ensure a conversation exists in the local channel cache.
+     * @internal
+     */
+    _ensureConversationImpl(conversationId: string): void;
     /**
      * Set a space-level metadata value.
      * Metadata is stored in meta and hidden from AI operations.
      */
     setMetadata(key: string, value: unknown): void;
+    /** @internal */
+    _setMetadataImpl(key: string, value: unknown, conversationId: string): void;
     /**
      * Get a space-level metadata value.
      */
@@ -254,6 +324,11 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
         message: string;
         objects: RoolObject[];
     }>;
+    /** @internal */
+    _promptImpl(prompt: string, options: PromptOptions | undefined, conversationId: string): Promise<{
+        message: string;
+        objects: RoolObject[];
+    }>;
     /**
      * Rename this channel.
      */
@@ -321,4 +396,60 @@ export declare class RoolChannel extends EventEmitter<ChannelEvents> {
      */
     private _handleObjectDeleted;
 }
+/**
+ * A lightweight handle for a specific conversation within a channel.
+ *
+ * Scopes AI and mutation operations to a particular conversation's interaction
+ * history, while sharing the channel's single SSE connection and object state.
+ *
+ * Obtain via `channel.conversation('thread-id')`.
+ * Conversations are auto-created on first interaction.
+ */
+export declare class ConversationHandle {
+    /** @internal */
+    private _channel;
+    private _conversationId;
+    /** @internal */
+    constructor(channel: RoolChannel, conversationId: string);
+    /** The conversation ID this handle is scoped to. */
+    get conversationId(): string;
+    /** Get interactions for this conversation. */
+    getInteractions(): Interaction[];
+    /** Get the system instruction for this conversation. */
+    getSystemInstruction(): string | undefined;
+    /** Set the system instruction for this conversation. Pass null to clear. */
+    setSystemInstruction(instruction: string | null): Promise<void>;
+    /** Rename this conversation. */
+    rename(name: string): Promise<void>;
+    /** Find objects using structured filters and/or natural language. */
+    findObjects(options: FindObjectsOptions): Promise<{
+        objects: RoolObject[];
+        message: string;
+    }>;
+    /** Create a new object. */
+    createObject(options: CreateObjectOptions): Promise<{
+        object: RoolObject;
+        message: string;
+    }>;
+    /** Update an existing object. */
+    updateObject(objectId: string, options: UpdateObjectOptions): Promise<{
+        object: RoolObject;
+        message: string;
+    }>;
+    /** Delete objects by IDs. */
+    deleteObjects(objectIds: string[]): Promise<void>;
+    /** Send a prompt to the AI agent, scoped to this conversation's history. */
+    prompt(text: string, options?: PromptOptions): Promise<{
+        message: string;
+        objects: RoolObject[];
+    }>;
+    /** Create a new collection schema. */
+    createCollection(name: string, fields: FieldDef[]): Promise<CollectionDef>;
+    /** Alter an existing collection schema. */
+    alterCollection(name: string, fields: FieldDef[]): Promise<CollectionDef>;
+    /** Drop a collection schema. */
+    dropCollection(name: string): Promise<void>;
+    /** Set a space-level metadata value. */
+    setMetadata(key: string, value: unknown): void;
+}
 //# sourceMappingURL=channel.d.ts.map