@rool-dev/sdk 0.9.0-dev.f75b2d1 → 0.10.0-dev.97d979e

package/dist/channel.js

@@ -1,10 +1,12 @@
 import { EventEmitter } from './event-emitter.js';
-// 6-character alphanumeric ID (62^6 = 56.8 billion possible values)
-const ID_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+import { generateBasename, loc, normalizeLocation, parseLocation } from './locations.js';
+import { resolveMachineResource } from './machine.js';
+// 6-character alphanumeric ID — used for interactionIds, conversationIds, etc.
+const ENTITY_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
 export function generateEntityId() {
     let result = '';
     for (let i = 0; i < 6; i++) {
-        result += ID_CHARS[Math.floor(Math.random() * ID_CHARS.length)];
+        result += ENTITY_CHARS[Math.floor(Math.random() * ENTITY_CHARS.length)];
     }
     return result;
 }
@@ -40,10 +42,10 @@ function findDefaultLeaf(interactions) {
     }
     return best?.id;
 }
-function attachmentBody(file, index) {
+function attachmentBody(file) {
     if (isFile(file)) {
         return {
-            filename: safeAttachmentFilename(file.name, index, file.type),
+            filename: safeAttachmentFilename(file.name, file.type),
             contentType: file.type || 'application/octet-stream',
             body: file,
         };
@@ -51,13 +53,13 @@ function attachmentBody(file, index) {
     if (isBlob(file)) {
         const contentType = file.type || 'application/octet-stream';
         return {
-            filename: safeAttachmentFilename(`attachment-${index + 1}`, index, contentType),
+            filename: safeAttachmentFilename('attachment', contentType),
             contentType,
             body: file,
         };
     }
     return {
-        filename: safeAttachmentFilename(`attachment-${index + 1}`, index, file.contentType),
+        filename: safeAttachmentFilename('attachment', file.contentType),
         contentType: file.contentType,
         body: base64Body(file.data),
     };
@@ -68,12 +70,11 @@ function isFile(value) {
 function isBlob(value) {
     return typeof Blob !== 'undefined' && value instanceof Blob;
 }
-function safeAttachmentFilename(name, index, contentType) {
+function safeAttachmentFilename(name, contentType) {
     const fallback = `attachment.${extensionForContentType(contentType)}`;
     const leaf = name.split(/[/\\]/).pop() || fallback;
     const cleaned = leaf.replace(/[\x00-\x1f\x7f]/g, '').replace(/\s+/g, '_');
-    const safe = cleaned.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+$/, '') || fallback;
-    return `${index + 1}-${safe}`;
+    return cleaned.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+$/, '') || fallback;
 }
 function extensionForContentType(contentType) {
     if (contentType === 'image/png')
@@ -123,16 +124,10 @@ const OBJECT_COLLECT_TIMEOUT = 30000;
  * at open time and cannot be changed. To use a different channel,
  * open a second one.
  *
- * Objects are fetched on demand from the server; only schema, metadata,
- * and the channel's own history are cached locally. Object changes
+ * Objects are addressed by location (`/space/<collection>/<basename>.json`).
+ * Only schema, metadata, the live object location list, and the channel's own
+ * history are cached locally. Object bodies are fetched on demand. Changes
  * arrive via SSE semantic events and are emitted as SDK events.
- *
- * Features:
- * - High-level object operations
- * - Built-in undo/redo with checkpoints
- * - Metadata management
- * - Event emission for state changes
- * - Real-time updates via space-specific subscription
  */
 export class RoolChannel extends EventEmitter {
     _id;
@@ -148,20 +143,20 @@ export class RoolChannel extends EventEmitter {
     webdav;
     onCloseCallback;
     logger;
-    // Local cache for bounded data (schema, metadata, own channel, object IDs, stats)
+    // Local cache for bounded data (schema, metadata, own channel, object locations, stats)
     _meta;
     _schema;
     _channel;
-    _objectIds;
+    _objectLocations;
     _objectStats;
     // Active leaf per conversation (client-side tree cursor)
     _activeLeaves = new Map();
-    // Object collection: tracks pending local mutations for dedup
-    // Maps objectId → optimistic object data (for create/update) or null (for delete)
+    // Object collection: tracks pending local mutations (by location) for dedup
+    // Maps location → optimistic object (for create/update) or null (for delete)
     _pendingMutations = new Map();
-    // Resolvers waiting for object data from SSE events
+    // Resolvers waiting for object data from SSE events, keyed by location
     _objectResolvers = new Map();
-    // Buffer for object data that arrived before a collector was registered
+    // Buffer for object data that arrived before a collector was registered, keyed by location
     _objectBuffer = new Map();
     constructor(config) {
         super();
@@ -182,7 +177,7 @@ export class RoolChannel extends EventEmitter {
         this._meta = config.meta;
         this._schema = config.schema;
         this._channel = config.channel;
-        this._objectIds = config.objectIds;
+        this._objectLocations = config.objectLocations;
         this._objectStats = new Map(Object.entries(config.objectStats));
     }
     /**
@@ -203,7 +198,7 @@ export class RoolChannel extends EventEmitter {
             return;
         this._meta = data.meta;
         this._schema = data.schema;
-        this._objectIds = data.objectIds;
+        this._objectLocations = data.objectLocations;
         this._objectStats = new Map(Object.entries(data.objectStats));
         if (data.channel)
             this._channel = data.channel;
@@ -370,10 +365,6 @@ export class RoolChannel extends EventEmitter {
     }
     /**
      * 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) {
         return new ConversationHandle(this, conversationId);
@@ -393,139 +384,109 @@ export class RoolChannel extends EventEmitter {
     }
     /**
      * Create a checkpoint of the current space state.
-     * Checkpoints are space-wide and shared across channels and users.
-     * @returns The checkpoint ID
      */
     async checkpoint(label = 'Change') {
         const result = await this.graphqlClient.checkpoint(this._id, label, this._channelId);
         return result.checkpointId;
     }
-    /**
-     * Check if undo is available for this space.
-     */
+    /** Check if undo is available for this space. */
     async canUndo() {
         const status = await this.graphqlClient.checkpointStatus(this._id, this._channelId);
         return status.canUndo;
     }
-    /**
-     * Check if redo is available for this space.
-     */
+    /** Check if redo is available for this space. */
     async canRedo() {
         const status = await this.graphqlClient.checkpointStatus(this._id, this._channelId);
         return status.canRedo;
     }
-    /**
-     * Restore the space to the most recent checkpoint.
-     * @returns true if undo was performed
-     */
+    /** Restore the space to the most recent checkpoint. */
     async undo() {
         const result = await this.graphqlClient.undo(this._id, this._channelId);
         return result.success;
     }
-    /**
-     * Reapply the most recently undone checkpoint.
-     * Affects the entire space.
-     * @returns true if redo was performed
-     */
+    /** Reapply the most recently undone checkpoint. */
     async redo() {
         const result = await this.graphqlClient.redo(this._id, this._channelId);
         return result.success;
     }
-    /**
-     * Clear the space's checkpoint history.
-     */
+    /** Clear the space's checkpoint history. */
     async clearHistory() {
         await this.graphqlClient.clearCheckpointHistory(this._id, this._channelId);
     }
     /**
-     * Get an object's data by ID.
-     * Fetches from the server on each call.
+     * Get an object by location. Fetches from the server on each call.
+     *
+     * Accepts either the canonical form (`/space/<collection>/<basename>.json`)
+     * or the short form (`<collection>/<basename>`).
      */
-    async getObject(objectId) {
-        return this.graphqlClient.getObject(this._id, objectId);
+    async getObject(location) {
+        return this.graphqlClient.getObject(this._id, normalizeLocation(location));
     }
     /**
      * Get an object's stat (audit information).
-     * Returns modification timestamp and author, or undefined if object not found.
+     * Returns the cached stat or undefined if not known.
      */
-    stat(objectId) {
-        return this._objectStats.get(objectId);
+    stat(location) {
+        return this._objectStats.get(normalizeLocation(location));
     }
     /**
      * Find objects using structured filters and/or natural language.
-     *
-     * `where` provides exact-match filtering — values must match literally (no placeholders or operators).
-     * `prompt` enables AI-powered semantic queries. When both are provided, `where` and `objectIds`
-     * constrain the data set before the AI sees it.
-     *
-     * @param options.where - Exact-match field filter (e.g. `{ type: 'article' }`). Constrains which objects the AI can see when combined with `prompt`.
-     * @param options.prompt - Natural language query. Triggers AI evaluation (uses credits).
-     * @param options.limit - Maximum number of results to return (applies to structured filtering only; the AI controls its own result size).
-     * @param options.objectIds - Scope search to specific object IDs. Constrains the candidate set in both structured and AI queries.
-     * @param options.order - Sort order by modifiedAt: `'asc'` or `'desc'` (default: `'desc'`). Only applies to structured filtering (no `prompt`).
-     * @param options.ephemeral - If true, the query won't be recorded in interaction history.
-     * @returns The matching objects and a descriptive message.
      */
     async findObjects(options) {
         return this._findObjectsImpl(options, this._conversationId);
     }
     /** @internal */
     _findObjectsImpl(options, conversationId) {
-        return this.graphqlClient.findObjects(this._id, options, this._channelId, conversationId);
+        const normalized = {
+            ...options,
+            locations: options.locations?.map(normalizeLocation),
+        };
+        return this.graphqlClient.findObjects(this._id, normalized, this._channelId, conversationId);
     }
     /**
-     * Get all object IDs (sync, from local cache).
+     * Get all object locations (sync, from local cache).
      * The list is loaded on open and kept current via SSE events.
-     * @param options.limit - Maximum number of IDs to return
-     * @param options.order - Sort order by modifiedAt ('asc' or 'desc', default: 'desc')
      */
-    getObjectIds(options) {
-        let ids = this._objectIds;
+    getObjectLocations(options) {
+        let locs = this._objectLocations;
         if (options?.order === 'asc') {
-            ids = [...ids].reverse();
+            locs = [...locs].reverse();
         }
         if (options?.limit !== undefined) {
-            ids = ids.slice(0, options.limit);
+            locs = locs.slice(0, options.limit);
         }
-        return ids;
+        return locs;
     }
     /**
-     * Create a new object with optional AI generation.
-     * @param options.data - Object data fields (any key-value pairs). Optionally include `id` to use a custom ID. Use {{placeholder}} for AI-generated content. Fields prefixed with _ are hidden from AI.
+     * Create a new object in the given collection.
+     *
+     * @param collection - The collection (must exist in the schema)
+     * @param body - Object body fields. Use `{{placeholder}}` for AI-generated content.
+     *               Fields prefixed with `_` are hidden from AI.
+     * @param options.basename - Specific basename to use. If omitted, the SDK generates a random one.
      * @param options.ephemeral - If true, the operation won't be recorded in interaction history.
-     * @returns The created object (with AI-filled content) and message
+     * @returns The created object and a status message.
      */
-    async createObject(options) {
-        return this._createObjectImpl(options, this._conversationId);
+    async createObject(collection, body, options) {
+        return this._createObjectImpl(collection, body, options, this._conversationId);
     }
     /** @internal */
-    async _createObjectImpl(options, conversationId) {
-        const { data, ephemeral } = options;
-        const basename = typeof data.id === 'string' ? data.id : generateEntityId();
-        const type = data.type;
-        if (!/^[a-zA-Z0-9_-]+$/.test(basename)) {
-            throw new Error(`Invalid object ID "${basename}". IDs must contain only alphanumeric characters, hyphens, and underscores.`);
-        }
-        if (typeof type !== 'string' || !type) {
-            throw new Error('createObject: data.type is required');
-        }
-        // Server's canonical id is "<type>/<basename>" — predict it locally so the
-        // optimistic event id matches the SSE echo, no dedup workaround needed.
-        const objectId = `${type}/${basename}`;
-        const dataForWire = { ...data, id: basename }; // server expects basename in data.id
-        const optimisticObject = { ...data, id: objectId }; // SDK tracks path-form
-        this._pendingMutations.set(objectId, optimisticObject);
-        this.emit('objectCreated', { objectId, object: optimisticObject, source: 'local_user' });
+    async _createObjectImpl(collection, body, options, conversationId) {
+        const basename = options?.basename ?? generateBasename();
+        const location = loc(collection, basename);
+        const optimistic = { location, collection, basename, body };
+        this._pendingMutations.set(location, optimistic);
+        this.emit('objectCreated', { location, object: optimistic, source: 'local_user' });
         try {
             const interactionId = generateEntityId();
-            const { message } = await this.graphqlClient.createObject(this.id, dataForWire, this._channelId, conversationId, interactionId, ephemeral);
-            const object = await this._collectObject(objectId);
-            return { object, message };
+            const { message, object } = await this.graphqlClient.createObject(this._id, location, body, this._channelId, conversationId, interactionId, { ephemeral: options?.ephemeral, parentInteractionId: options?.parentInteractionId });
+            const fresh = object ?? await this._collectObject(location);
+            return { object: fresh, message };
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to create object:', error);
-            this._pendingMutations.delete(objectId);
-            this._cancelCollector(objectId);
+            this._pendingMutations.delete(location);
+            this._cancelCollector(location);
             this.emit('syncError', error instanceof Error ? error : new Error(String(error)));
             this.emit('reset', { source: 'system' });
             throw error;
@@ -533,98 +494,135 @@ export class RoolChannel extends EventEmitter {
     }
     /**
      * Update an existing object.
-     * @param objectId - The ID of the object to update
-     * @param options.data - Fields to add or update. Pass null or undefined to delete a field. Use {{placeholder}} for AI-generated content. Fields prefixed with _ are hidden from AI.
-     * @param options.prompt - AI prompt for content editing (optional).
+     *
+     * @param location - The object's location (canonical or short form)
+     * @param options.data - Fields to add or update. Pass `null` to delete a field. Use `{{placeholder}}` for AI-generated content.
+     * @param options.prompt - AI prompt to drive the update.
      * @param options.ephemeral - If true, the operation won't be recorded in interaction history.
-     * @returns The updated object (with AI-filled content) and message
      */
-    async updateObject(objectId, options) {
-        return this._updateObjectImpl(objectId, options, this._conversationId);
+    async updateObject(location, options) {
+        return this._updateObjectImpl(location, options, this._conversationId);
     }
     /** @internal */
-    async _updateObjectImpl(objectId, options, conversationId) {
-        const { data, ephemeral } = options;
-        // id is immutable after creation (but null/undefined means delete attempt, which we also reject)
-        if (data?.id !== undefined && data.id !== null) {
-            throw new Error('Cannot change id in updateObject. The id field is immutable after creation.');
-        }
-        if (data && ('id' in data)) {
-            throw new Error('Cannot delete id field. The id field is immutable after creation.');
-        }
-        // Normalize undefined to null (for JSON serialization) and build server data
-        let serverData;
+    async _updateObjectImpl(location, options, conversationId) {
+        const canonical = normalizeLocation(location);
+        const { data } = options;
+        // Normalize undefined to null (for JSON serialization) and build server patch
+        let serverPatch;
         if (data) {
-            serverData = {};
+            serverPatch = {};
             for (const [key, value] of Object.entries(data)) {
-                // Convert undefined to null for wire protocol
-                serverData[key] = value === undefined ? null : value;
+                serverPatch[key] = value === undefined ? null : value;
             }
         }
         // Emit optimistic event if we have data changes
         if (data) {
-            // Build optimistic object (best effort — we may not have the current state)
-            const optimistic = { id: objectId, ...data };
-            this._pendingMutations.set(objectId, optimistic);
-            this.emit('objectUpdated', { objectId, object: optimistic, source: 'local_user' });
+            const { collection, basename } = parseLocation(canonical);
+            const optimistic = { location: canonical, collection, basename, body: data };
+            this._pendingMutations.set(canonical, optimistic);
+            this.emit('objectUpdated', { location: canonical, object: optimistic, source: 'local_user' });
         }
         try {
             const interactionId = generateEntityId();
-            const { message } = await this.graphqlClient.updateObject(this.id, objectId, this._channelId, conversationId, interactionId, serverData, options.prompt, ephemeral);
-            const object = await this._collectObject(objectId);
-            return { object, message };
+            const { message, object } = await this.graphqlClient.updateObject(this._id, canonical, this._channelId, conversationId, interactionId, {
+                patch: serverPatch,
+                prompt: options.prompt,
+                ephemeral: options.ephemeral,
+                parentInteractionId: options.parentInteractionId,
+            });
+            const fresh = object ?? await this._collectObject(canonical);
+            return { object: fresh, message };
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to update object:', error);
-            this._pendingMutations.delete(objectId);
-            this._cancelCollector(objectId);
+            this._pendingMutations.delete(canonical);
+            this._cancelCollector(canonical);
             this.emit('syncError', error instanceof Error ? error : new Error(String(error)));
             this.emit('reset', { source: 'system' });
             throw error;
         }
     }
     /**
-     * Delete objects by IDs.
-     * Other objects that reference deleted objects via data fields will retain stale ref values.
+     * Move (rename or relocate) an object to a new location.
+     * Use this to rename, change collection, or atomically rewrite the body.
+     *
+     * @param from - Current location
+     * @param to - New location
+     * @param options.body - Replace the body atomically as part of the move.
+     * @param options.ephemeral - If true, the operation won't be recorded in interaction history.
      */
-    async deleteObjects(objectIds) {
-        return this._deleteObjectsImpl(objectIds, this._conversationId);
+    async moveObject(from, to, options) {
+        return this._moveObjectImpl(from, to, options, this._conversationId);
     }
     /** @internal */
-    async _deleteObjectsImpl(objectIds, conversationId) {
-        if (objectIds.length === 0)
+    async _moveObjectImpl(from, to, options, conversationId) {
+        const fromLoc = normalizeLocation(from);
+        const toLoc = normalizeLocation(to);
+        // Optimistic event — emit move so listeners can update keys
+        const { collection, basename } = parseLocation(toLoc);
+        const optimistic = {
+            location: toLoc,
+            collection,
+            basename,
+            body: options?.body ?? {},
+        };
+        this._pendingMutations.set(toLoc, optimistic);
+        this.emit('objectMoved', { from: fromLoc, to: toLoc, object: optimistic, source: 'local_user' });
+        try {
+            const interactionId = generateEntityId();
+            const { message, object } = await this.graphqlClient.moveObject(this._id, fromLoc, toLoc, this._channelId, conversationId, interactionId, {
+                body: options?.body,
+                ephemeral: options?.ephemeral,
+                parentInteractionId: options?.parentInteractionId,
+            });
+            const fresh = object ?? await this._collectObject(toLoc);
+            return { object: fresh, message };
+        }
+        catch (error) {
+            this.logger.error('[RoolChannel] Failed to move object:', error);
+            this._pendingMutations.delete(toLoc);
+            this._cancelCollector(toLoc);
+            this.emit('syncError', error instanceof Error ? error : new Error(String(error)));
+            this.emit('reset', { source: 'system' });
+            throw error;
+        }
+    }
+    /**
+     * Delete objects by location.
+     * Other objects that reference deleted objects will retain stale ref values.
+     */
+    async deleteObjects(locations) {
+        return this._deleteObjectsImpl(locations, this._conversationId);
+    }
+    /** @internal */
+    async _deleteObjectsImpl(locations, conversationId) {
+        if (locations.length === 0)
             return;
+        const canonical = locations.map(normalizeLocation);
         // Track for dedup and emit optimistic events
-        for (const objectId of objectIds) {
-            this._pendingMutations.set(objectId, null);
-            this.emit('objectDeleted', { objectId, source: 'local_user' });
+        for (const location of canonical) {
+            this._pendingMutations.set(location, null);
+            this.emit('objectDeleted', { location, source: 'local_user' });
         }
         try {
-            await this.graphqlClient.deleteObjects(this.id, objectIds, this._channelId, conversationId);
+            const interactionId = generateEntityId();
+            await this.graphqlClient.deleteObjects(this._id, canonical, this._channelId, conversationId, interactionId);
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to delete objects:', error);
-            for (const objectId of objectIds) {
-                this._pendingMutations.delete(objectId);
+            for (const location of canonical) {
+                this._pendingMutations.delete(location);
             }
             this.emit('syncError', error instanceof Error ? error : new Error(String(error)));
             this.emit('reset', { source: 'system' });
             throw error;
         }
     }
-    /**
-     * Get the current schema for this space.
-     * Returns a map of collection names to their definitions.
-     */
+    /** Get the current schema for this space. */
     getSchema() {
         return this._schema;
     }
-    /**
-     * Create a new collection schema.
-     * @param name - Collection name (must start with a letter, alphanumeric/hyphens/underscores only)
-     * @param fields - Field definitions for the collection
-     * @returns The created CollectionDef
-     */
+    /** Create a new collection schema. */
     async createCollection(name, fields) {
         return this._createCollectionImpl(name, fields, this._conversationId);
     }
@@ -645,12 +643,7 @@ export class RoolChannel extends EventEmitter {
             throw error;
         }
     }
-    /**
-     * Alter an existing collection schema, replacing its field definitions.
-     * @param name - Name of the collection to alter
-     * @param fields - New field definitions (replaces all existing fields)
-     * @returns The updated CollectionDef
-     */
+    /** Alter an existing collection schema, replacing its field definitions. */
     async alterCollection(name, fields) {
         return this._alterCollectionImpl(name, fields, this._conversationId);
     }
@@ -660,7 +653,6 @@ export class RoolChannel extends EventEmitter {
             throw new Error(`Collection "${name}" not found`);
         }
         const previous = this._schema[name];
-        // Optimistic local update
         this._schema[name] = { fields: fields.map(f => ({ name: f.name, type: f.type })) };
         try {
             return await this.graphqlClient.alterCollection(this._id, name, fields, this._channelId, conversationId);
@@ -671,10 +663,7 @@ export class RoolChannel extends EventEmitter {
             throw error;
         }
     }
-    /**
-     * Drop a collection schema.
-     * @param name - Name of the collection to drop
-     */
+    /** Drop a collection schema. */
     async dropCollection(name) {
         return this._dropCollectionImpl(name, this._conversationId);
     }
@@ -684,7 +673,6 @@ export class RoolChannel extends EventEmitter {
             throw new Error(`Collection "${name}" not found`);
         }
         const previous = this._schema[name];
-        // Optimistic local update
         delete this._schema[name];
         try {
             await this.graphqlClient.dropCollection(this._id, name, this._channelId, conversationId);
@@ -697,7 +685,6 @@ export class RoolChannel extends EventEmitter {
     }
     /**
      * Get the system instruction for the current conversation.
-     * Returns undefined if no system instruction is set.
      */
     getSystemInstruction() {
         return this._getSystemInstructionImpl(this._conversationId);
@@ -706,16 +693,12 @@ export class RoolChannel extends EventEmitter {
     _getSystemInstructionImpl(conversationId) {
         return this._channel?.conversations[conversationId]?.systemInstruction;
     }
-    /**
-     * Set the system instruction for the current conversation.
-     * Pass null to clear the instruction.
-     */
+    /** Set the system instruction for the current conversation. */
     async setSystemInstruction(instruction) {
         return this._setSystemInstructionImpl(instruction, this._conversationId);
     }
     /** @internal */
     async _setSystemInstructionImpl(instruction, conversationId) {
-        // Optimistic local update
         this._ensureConversationImpl(conversationId);
         const conv = this._channel.conversations[conversationId];
         const previousInstruction = conv.systemInstruction;
@@ -725,7 +708,6 @@ export class RoolChannel extends EventEmitter {
         else {
             conv.systemInstruction = instruction;
         }
-        // Emit events for backward compat and new API
         this.emit('conversationUpdated', {
             conversationId,
             channelId: this._channelId,
@@ -737,13 +719,11 @@ export class RoolChannel extends EventEmitter {
                 source: 'local_user',
             });
         }
-        // Call server
         try {
             await this.graphqlClient.updateConversation(this._id, this._channelId, conversationId, { systemInstruction: instruction });
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to set system instruction:', error);
-            // Rollback
             if (previousInstruction === undefined) {
                 delete conv.systemInstruction;
             }
@@ -753,15 +733,12 @@ export class RoolChannel extends EventEmitter {
             throw error;
         }
     }
-    /**
-     * Rename the current conversation.
-     */
+    /** Rename the current conversation. */
     async renameConversation(name) {
         return this._renameConversationImpl(name, this._conversationId);
     }
     /** @internal */
     async _renameConversationImpl(name, conversationId) {
-        // Optimistic local update
         this._ensureConversationImpl(conversationId);
         const conv = this._channel.conversations[conversationId];
         const previousName = conv.name;
@@ -777,21 +754,16 @@ export class RoolChannel extends EventEmitter {
                 source: 'local_user',
             });
         }
-        // Call server
         try {
             await this.graphqlClient.updateConversation(this._id, this._channelId, conversationId, { name });
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to rename conversation:', error);
-            // Rollback
             conv.name = previousName;
             throw error;
         }
     }
-    /**
-     * Ensure a conversation exists in the local channel cache.
-     * @internal
-     */
+    /** @internal */
     _ensureConversationImpl(conversationId) {
         if (!this._channel) {
             this._channel = {
@@ -808,10 +780,7 @@ export class RoolChannel extends EventEmitter {
             };
         }
     }
-    /**
-     * Set a space-level metadata value.
-     * Metadata is stored in meta and hidden from AI operations.
-     */
+    /** Set a space-level metadata value. */
     setMetadata(key, value) {
         this._setMetadataImpl(key, value, this._conversationId);
     }
@@ -820,38 +789,34 @@ export class RoolChannel extends EventEmitter {
         this._meta[key] = value;
         this.emit('metadataUpdated', { metadata: this._meta, source: 'local_user' });
         // Fire-and-forget server call
-        this.graphqlClient.setSpaceMeta(this.id, this._meta, this._channelId, conversationId)
+        this.graphqlClient.setSpaceMeta(this._id, this._meta, this._channelId, conversationId)
             .catch((error) => {
             this.logger.error('[RoolChannel] Failed to set meta:', error);
         });
     }
-    /**
-     * Get a space-level metadata value.
-     */
+    /** Get a space-level metadata value. */
     getMetadata(key) {
         return this._meta[key];
     }
-    /**
-     * Get all space-level metadata.
-     */
+    /** Get all space-level metadata. */
     getAllMetadata() {
         return this._meta;
     }
     /**
      * Send a prompt to the AI agent for space manipulation.
-     * @returns The message from the AI and the list of objects that were created or modified
+     * @returns The message from the AI and the list of objects that were created or modified.
      */
     async prompt(prompt, options) {
         return this._promptImpl(prompt, options, this._conversationId);
     }
     /** @internal */
     async _promptImpl(prompt, options, conversationId) {
-        // Attachments become rool-drive:/ file references stored on the interaction.
-        const { attachments, parentInteractionId: explicitParent, signal, ...rest } = options ?? {};
+        const { attachments, parentInteractionId: explicitParent, signal, locations, ...rest } = options ?? {};
         const interactionId = generateEntityId();
-        let attachmentUrls;
+        let attachmentRefs;
         if (attachments?.length) {
-            attachmentUrls = await Promise.all(attachments.map((file, index) => this.uploadAttachment(file, interactionId, index)));
+            const resources = await Promise.all(attachments.map((file) => this.uploadAttachment(file, conversationId)));
+            attachmentRefs = resources.map((resource) => `rool-machine:${resource.path.split('/').map(encodeURIComponent).join('/')}`);
         }
         // Auto-continue from active leaf if no explicit parent provided
         const parentInteractionId = explicitParent !== undefined
@@ -862,8 +827,6 @@ export class RoolChannel extends EventEmitter {
         let onAbort;
         if (signal) {
             if (signal.aborted) {
-                // Caller aborted before we even started; fire-and-forget the stop so
-                // the server-side prompt (about to start) is cancelled too.
                 this.graphqlClient.stopInteraction(this._id, interactionId).catch(() => { });
             }
             else {
@@ -875,29 +838,33 @@ export class RoolChannel extends EventEmitter {
         }
         let result;
         try {
-            result = await this.graphqlClient.prompt(this._id, prompt, this._channelId, conversationId, { ...rest, attachmentUrls, interactionId, parentInteractionId });
+            result = await this.graphqlClient.prompt(this._id, prompt, this._channelId, conversationId, {
+                ...rest,
+                locations: locations?.map(normalizeLocation),
+                attachmentRefs,
+                interactionId,
+                parentInteractionId,
+            });
         }
         finally {
             if (onAbort)
                 signal.removeEventListener('abort', onAbort);
         }
         // Collect modified objects — they arrive via SSE events during/after the mutation.
-        // Try collecting from buffer first, then fetch any missing from server.
         const objects = [];
         const missing = [];
-        for (const id of result.modifiedObjectIds) {
-            const buffered = this._objectBuffer.get(id);
+        for (const location of result.modifiedObjectLocations) {
+            const buffered = this._objectBuffer.get(location);
             if (buffered) {
-                this._objectBuffer.delete(id);
+                this._objectBuffer.delete(location);
                 objects.push(buffered);
             }
             else {
-                missing.push(id);
+                missing.push(location);
             }
         }
-        // Fetch any objects not yet received via SSE
         if (missing.length > 0) {
-            const fetched = await Promise.all(missing.map(id => this.graphqlClient.getObject(this._id, id)));
+            const fetched = await Promise.all(missing.map(location => this.graphqlClient.getObject(this._id, location)));
             for (const obj of fetched) {
                 if (obj)
                     objects.push(obj);
@@ -908,23 +875,18 @@ export class RoolChannel extends EventEmitter {
             objects,
         };
     }
-    /**
-     * Rename this channel.
-     */
+    /** Rename this channel. */
     async rename(newName) {
-        // Optimistic local update
         const previousName = this._channel?.name;
         if (this._channel) {
             this._channel.name = newName;
         }
         this.emit('channelUpdated', { channelId: this._channelId, source: 'local_user' });
-        // Call server
         try {
             await this.graphqlClient.renameChannel(this._id, this._channelId, newName);
         }
         catch (error) {
             this.logger.error('[RoolChannel] Failed to rename channel:', error);
-            // Rollback
             if (this._channel) {
                 this._channel.name = previousName;
             }
@@ -933,25 +895,24 @@ export class RoolChannel extends EventEmitter {
     }
     /**
      * Fetch an external URL via the server proxy, bypassing CORS restrictions.
-     * Requires editor role or above. Blocked for private/internal IP ranges (SSRF protection).
-     *
-     * @param url - The URL to fetch
-     * @param init - Optional method, headers, and body
-     * @returns The proxied Response
      */
     async fetch(url, init) {
         return this.restClient.proxyFetch(this._id, url, init);
     }
-    async uploadAttachment(file, interactionId, index) {
+    async uploadAttachment(file, conversationId) {
         await this.ensureCollection('attachments');
-        const directory = `attachments/${interactionId}`;
+        const directory = `attachments/${conversationId}`;
         await this.ensureCollection(directory);
-        const attachment = attachmentBody(file, index);
+        const attachment = attachmentBody(file);
         const path = `${directory}/${attachment.filename}`;
         await this.webdav.put(path, attachment.body, { contentType: attachment.contentType });
-        return this.webdav.ref(path);
+        const resource = resolveMachineResource(`/rool-drive/${path}`);
+        if (!resource)
+            throw new Error('Failed to resolve uploaded attachment');
+        return resource;
     }
     async ensureCollection(path) {
+        // Note: not an object collection, a folder, which is "collection" in webdav land
         const response = await this.webdav.request('MKCOL', path, { collection: true });
         if (response.status === 201 || response.status === 405)
             return;
@@ -959,57 +920,48 @@ export class RoolChannel extends EventEmitter {
     }
     /**
      * Register a collector that resolves when the object arrives via SSE.
-     * If the object is already in the buffer (arrived before collector), resolves immediately.
      * @internal
      */
-    _collectObject(objectId) {
+    _collectObject(location) {
         return new Promise((resolve, reject) => {
-            // Check buffer first — SSE event may have arrived before the HTTP response
-            const buffered = this._objectBuffer.get(objectId);
+            const buffered = this._objectBuffer.get(location);
             if (buffered) {
-                this._objectBuffer.delete(objectId);
+                this._objectBuffer.delete(location);
                 resolve(buffered);
                 return;
             }
             const timer = setTimeout(() => {
-                this._objectResolvers.delete(objectId);
+                this._objectResolvers.delete(location);
                 // Fallback: try to fetch from server
-                this.graphqlClient.getObject(this._id, objectId).then(obj => {
+                this.graphqlClient.getObject(this._id, location).then(obj => {
                     if (obj) {
                         resolve(obj);
                     }
                     else {
-                        reject(new Error(`Timeout waiting for object ${objectId} from SSE`));
+                        reject(new Error(`Timeout waiting for object ${location} from SSE`));
                     }
                 }).catch(reject);
             }, OBJECT_COLLECT_TIMEOUT);
-            this._objectResolvers.set(objectId, (obj) => {
+            this._objectResolvers.set(location, (obj) => {
                 clearTimeout(timer);
                 resolve(obj);
             });
         });
     }
-    /**
-     * Cancel a pending object collector (e.g., on mutation error).
-     * @internal
-     */
-    _cancelCollector(objectId) {
-        this._objectResolvers.delete(objectId);
-        this._objectBuffer.delete(objectId);
+    /** @internal */
+    _cancelCollector(location) {
+        this._objectResolvers.delete(location);
+        this._objectBuffer.delete(location);
     }
-    /**
-     * Deliver an object to a pending collector, or buffer it for later collection.
-     * @internal
-     */
-    _deliverObject(objectId, object) {
-        const resolver = this._objectResolvers.get(objectId);
+    /** @internal */
+    _deliverObject(location, object) {
+        const resolver = this._objectResolvers.get(location);
         if (resolver) {
             resolver(object);
-            this._objectResolvers.delete(objectId);
+            this._objectResolvers.delete(location);
         }
         else {
-            // Buffer for prompt() or late collectors
-            this._objectBuffer.set(objectId, object);
+            this._objectBuffer.set(location, object);
         }
     }
     /**
@@ -1017,7 +969,6 @@ export class RoolChannel extends EventEmitter {
      * @internal
      */
     handleChannelEvent(event) {
-        // Ignore events after close - the channel is being torn down
         if (this._closed)
             return;
         const changeSource = event.source === 'agent' ? 'remote_agent' : 'remote_user';
@@ -1026,23 +977,31 @@ export class RoolChannel extends EventEmitter {
                 // Resync is handled by the client via _applyResyncData.
                 break;
             case 'object_created':
-                if (event.objectId && event.object) {
+                if (event.location && event.object) {
                     if (event.objectStat)
-                        this._objectStats.set(event.objectId, event.objectStat);
-                    this._handleObjectCreated(event.objectId, event.object, changeSource);
+                        this._objectStats.set(event.location, event.objectStat);
+                    this._handleObjectCreated(event.location, event.object, changeSource);
                 }
                 break;
             case 'object_updated':
-                if (event.objectId && event.object) {
+                if (event.location && event.object) {
                     if (event.objectStat)
-                        this._objectStats.set(event.objectId, event.objectStat);
-                    this._handleObjectUpdated(event.objectId, event.object, changeSource);
+                        this._objectStats.set(event.location, event.objectStat);
+                    this._handleObjectUpdated(event.location, event.object, changeSource);
                 }
                 break;
             case 'object_deleted':
-                if (event.objectId) {
-                    this._objectStats.delete(event.objectId);
-                    this._handleObjectDeleted(event.objectId, changeSource);
+                if (event.location) {
+                    this._objectStats.delete(event.location);
+                    this._handleObjectDeleted(event.location, changeSource);
+                }
+                break;
+            case 'object_moved':
+                if (event.from && event.to && event.object) {
+                    this._objectStats.delete(event.from);
+                    if (event.objectStat)
+                        this._objectStats.set(event.to, event.objectStat);
+                    this._handleObjectMoved(event.from, event.to, event.object, changeSource);
                 }
                 break;
             case 'schema_updated':
@@ -1058,7 +1017,6 @@ export class RoolChannel extends EventEmitter {
                 }
                 break;
             case 'channel_updated':
-                // Only update if it's our channel — channel_updated is now metadata-only (name, extensionUrl)
                 if (event.channelId === this._channelId && event.channel) {
                     const changed = JSON.stringify(this._channel) !== JSON.stringify(event.channel);
                     this._channel = event.channel;
@@ -1068,7 +1026,6 @@ export class RoolChannel extends EventEmitter {
                 }
                 break;
             case 'conversation_updated':
-                // Only update if it's our channel
                 if (event.channelId === this._channelId && event.conversationId) {
                     if (!this._channel) {
                         this._channel = {
@@ -1079,17 +1036,13 @@ export class RoolChannel extends EventEmitter {
                     }
                     const prev = this._channel.conversations[event.conversationId];
                     if (event.conversation) {
-                        // Update or create conversation in local cache
                         this._channel.conversations[event.conversationId] = event.conversation;
                     }
                     else {
-                        // Conversation was deleted
                         delete this._channel.conversations[event.conversationId];
                     }
-                    // Skip emit if data is unchanged (e.g. echo of our own optimistic update)
                     if (JSON.stringify(prev) === JSON.stringify(event.conversation))
                         break;
-                    // Auto-advance active leaf if someone continued our current branch
                     if (event.conversation && !Array.isArray(event.conversation.interactions)) {
                         const currentLeaf = this._getActiveLeafImpl(event.conversationId);
                         if (currentLeaf) {
@@ -1101,13 +1054,11 @@ export class RoolChannel extends EventEmitter {
                             }
                         }
                     }
-                    // Emit the new conversationUpdated event
                     this.emit('conversationUpdated', {
                         conversationId: event.conversationId,
                         channelId: event.channelId,
                         source: changeSource,
                     });
-                    // Backward compat: also emit channelUpdated when the active conversation updates
                     if (event.conversationId === this._conversationId) {
                         this.emit('channelUpdated', { channelId: event.channelId, source: changeSource });
                     }
@@ -1118,87 +1069,75 @@ export class RoolChannel extends EventEmitter {
                 break;
         }
     }
-    /**
-     * Handle an object_created SSE event.
-     * Deduplicates against optimistic local creates.
-     * @internal
-     */
-    _handleObjectCreated(objectId, object, source) {
-        // Deliver to any pending collector (for mutation return values)
-        this._deliverObject(objectId, object);
-        // Maintain local ID list — prepend (most recently modified first)
-        this._objectIds = [objectId, ...this._objectIds.filter(id => id !== objectId)];
-        const pending = this._pendingMutations.get(objectId);
+    /** @internal */
+    _handleObjectCreated(location, object, source) {
+        this._deliverObject(location, object);
+        // Maintain local location list — prepend (most recently modified first)
+        this._objectLocations = [location, ...this._objectLocations.filter(l => l !== location)];
+        const pending = this._pendingMutations.get(location);
         if (pending !== undefined) {
-            // This is our own mutation echoed back
-            this._pendingMutations.delete(objectId);
+            this._pendingMutations.delete(location);
             if (pending !== null) {
-                // It was a create — already emitted objectCreated optimistically.
+                // Already emitted objectCreated optimistically.
                 // Emit objectUpdated only if AI resolved placeholders (data changed).
                 if (JSON.stringify(pending) !== JSON.stringify(object)) {
-                    this.emit('objectUpdated', { objectId, object, source });
+                    this.emit('objectUpdated', { location, object, source });
                 }
             }
         }
         else {
-            // Remote event — emit normally
-            this.emit('objectCreated', { objectId, object, source });
+            this.emit('objectCreated', { location, object, source });
         }
     }
-    /**
-     * Handle an object_updated SSE event.
-     * Deduplicates against optimistic local updates.
-     * @internal
-     */
-    _handleObjectUpdated(objectId, object, source) {
-        // Deliver to any pending collector
-        this._deliverObject(objectId, object);
-        // Maintain local ID list — move to front (most recently modified)
-        this._objectIds = [objectId, ...this._objectIds.filter(id => id !== objectId)];
-        const pending = this._pendingMutations.get(objectId);
+    /** @internal */
+    _handleObjectUpdated(location, object, source) {
+        this._deliverObject(location, object);
+        this._objectLocations = [location, ...this._objectLocations.filter(l => l !== location)];
+        const pending = this._pendingMutations.get(location);
         if (pending !== undefined) {
-            // This is our own mutation echoed back
-            this._pendingMutations.delete(objectId);
+            this._pendingMutations.delete(location);
             if (pending !== null) {
-                // Already emitted objectUpdated optimistically.
-                // Emit again only if data changed (AI resolved placeholders).
                 if (JSON.stringify(pending) !== JSON.stringify(object)) {
-                    this.emit('objectUpdated', { objectId, object, source });
+                    this.emit('objectUpdated', { location, object, source });
                 }
             }
         }
         else {
-            // Remote event
-            this.emit('objectUpdated', { objectId, object, source });
+            this.emit('objectUpdated', { location, object, source });
         }
     }
-    /**
-     * Handle an object_deleted SSE event.
-     * Deduplicates against optimistic local deletes.
-     * @internal
-     */
-    _handleObjectDeleted(objectId, source) {
-        // Remove from local ID list
-        this._objectIds = this._objectIds.filter(id => id !== objectId);
-        const pending = this._pendingMutations.get(objectId);
+    /** @internal */
+    _handleObjectDeleted(location, source) {
+        this._objectLocations = this._objectLocations.filter(l => l !== location);
+        const pending = this._pendingMutations.get(location);
         if (pending !== undefined) {
-            // This is our own delete echoed back — already emitted
-            this._pendingMutations.delete(objectId);
+            this._pendingMutations.delete(location);
         }
         else {
-            // Remote event
-            this.emit('objectDeleted', { objectId, source });
+            this.emit('objectDeleted', { location, source });
+        }
+    }
+    /** @internal */
+    _handleObjectMoved(from, to, object, source) {
+        this._deliverObject(to, object);
+        // Drop old location, insert new one at the front.
+        this._objectLocations = [to, ...this._objectLocations.filter(l => l !== from && l !== to)];
+        const pending = this._pendingMutations.get(to);
+        if (pending !== undefined) {
+            this._pendingMutations.delete(to);
+            if (pending !== null) {
+                if (JSON.stringify(pending) !== JSON.stringify(object)) {
+                    this.emit('objectUpdated', { location: to, object, source });
+                }
+            }
+        }
+        else {
+            this.emit('objectMoved', { from, to, object, source });
         }
     }
 }
 /**
  * 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 class ConversationHandle {
     /** @internal */
@@ -1244,16 +1183,20 @@ export class ConversationHandle {
         return this._channel._findObjectsImpl(options, this._conversationId);
     }
     /** Create a new object. */
-    async createObject(options) {
-        return this._channel._createObjectImpl(options, this._conversationId);
+    async createObject(collection, body, options) {
+        return this._channel._createObjectImpl(collection, body, options, this._conversationId);
     }
     /** Update an existing object. */
-    async updateObject(objectId, options) {
-        return this._channel._updateObjectImpl(objectId, options, this._conversationId);
+    async updateObject(location, options) {
+        return this._channel._updateObjectImpl(location, options, this._conversationId);
+    }
+    /** Move (rename/relocate) an object. */
+    async moveObject(from, to, options) {
+        return this._channel._moveObjectImpl(from, to, options, this._conversationId);
     }
-    /** Delete objects by IDs. */
-    async deleteObjects(objectIds) {
-        return this._channel._deleteObjectsImpl(objectIds, this._conversationId);
+    /** Delete objects by location. */
+    async deleteObjects(locations) {
+        return this._channel._deleteObjectsImpl(locations, this._conversationId);
     }
     /** Send a prompt to the AI agent, scoped to this conversation's history. */
     async prompt(text, options) {