@rool-dev/sdk 0.10.1 → 0.10.2-dev.0bf8edb

package/README.md

@@ -2,8 +2,6 @@
 
 The TypeScript SDK for Rool, a persistent and collaborative environment for organizing objects.
 
-> **Building a new Rool extension?** Start with [`@rool-dev/extension`](/extension/) — 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 extension sandbox.
-
 The SDK manages authentication, real-time synchronization, and per-space file storage. Core primitives:
 
 - **Spaces** — Containers for objects, schema, metadata, channels, and files
@@ -65,10 +63,9 @@ const { message, objects } = await channel.prompt(
 console.log(message);  // AI explains what it did
 console.log(`Modified ${objects.length} objects`);
 
-// Query with natural language
-const { objects: innerPlanets } = await channel.findObjects({
-  prompt: 'planets closer to the sun than Earth'
-});
+// Read an object by location
+const loadedEarth = await channel.getObject(earth.location);
+console.log(loadedEarth?.body.name);
 
 // Clean up
 channel.close();
@@ -229,7 +226,7 @@ References are just data — no special API is needed to create or remove them.
 #### Location helpers
 
 ```typescript
-import { loc, parseLocation, normalizeLocation, generateBasename } from '@rool-dev/sdk';
+import { loc, parseLocation, normalizeLocation } from '@rool-dev/sdk';
 
 loc('article', 'welcome');                  // '/space/article/welcome.json'
 parseLocation('/space/article/welcome.json'); // { collection: 'article', basename: 'welcome' }
@@ -237,9 +234,6 @@ parseLocation('/space/article/welcome.json'); // { collection: 'article', basena
 // normalizeLocation accepts canonical or short form and returns canonical
 normalizeLocation('article/welcome');         // '/space/article/welcome.json'
 normalizeLocation('/space/article/welcome.json'); // unchanged
-
-// 6-char random basename — same generator the SDK uses by default
-generateBasename();                           // e.g., 'X7kQ9p'
 ```
 
 SDK methods that accept a location (`getObject`, `updateObject`, `deleteObjects`, `moveObject`, etc.) accept either form and normalize internally. SDK return values always use the canonical full form.
@@ -320,24 +314,24 @@ await channel.createObject('article', {
 
 ### Real-time Sync
 
-Events fire for both local and remote changes. The `source` field indicates origin:
-
-- `local_user` — This client made the change
-- `remote_user` — Another user/client made the change
-- `remote_agent` — AI agent made the change
-- `system` — Resync after error
+Object and file reactivity is WebDAV-based. Listen for space-level file change notifications, then reconcile with `webdav.syncCollection()` using your sync token. This covers both object files under `/space` and user files under `/rool-drive`.
 
 ```typescript
-// All UI updates happen in one place, regardless of change source
-channel.on('objectUpdated', ({ location, object, source }) => {
-  renderObject(location, object);
-  if (source === 'remote_agent') {
-    doLayout(); // AI might have added content
-  }
-});
+let token: string | null = null;
+
+async function syncFiles() {
+  const result = await space.webdav.syncCollection('/', {
+    token,
+    level: 'infinite',
+    props: ['displayname', 'getetag', 'getlastmodified', 'resourcetype'],
+  });
+  token = result.token;
+  updateFileTree(result.responses);
+}
 
-// Caller just makes the change - event handler does the UI work
-channel.updateObject(location, { prompt: 'expand this' });
+space.on('filesChanged', syncFiles);
+space.on('filesReset', () => { token = null; syncFiles(); });
+await syncFiles();
 ```
 
 ### Locations & Basenames
@@ -358,7 +352,7 @@ await channel.createObject('article',
 
 ```typescript
 // Fire-and-forget: create and reference without waiting
-const basename = RoolClient.generateBasename();
+const basename = 'idea-seed';
 const location = loc('note', basename);
 
 channel.createObject('note', { text: '{{expand this idea}}' }, { basename });
@@ -443,13 +437,12 @@ Returns a message (the AI's response) and the list of objects that were created
 
 | Option | Description |
 |--------|-------------|
-| `locations` | Focus the AI on specific objects, identified by location (given primary attention in context). |
 | `responseSchema` | Request structured JSON instead of text summary |
 | `effort` | Effort level: `'QUICK'`, `'STANDARD'` (default), `'REASONING'`, or `'RESEARCH'` |
 | `ephemeral` | If true, don't record in interaction history (useful for tab completion) |
 | `readOnly` | If true, disable mutation tools (create, update, move, delete). Use for questions. |
 | `parentInteractionId` | Parent interaction in the conversation tree. Omit to auto-continue from the active leaf. Pass `null` to start a new root-level branch. Pass a specific ID to branch from that point (edit/reroll). |
-| `attachments` | Files to attach (`File`, `Blob`, or `{ data, contentType }`). Stored as authenticated space files; resulting `rool-machine:/rool-drive/...` references are stored on the interaction's `attachments` field for UI rendering. The AI can interpret images (JPEG, PNG, GIF, WebP, SVG), PDFs, text-based files (plain text, Markdown, CSV, HTML, XML, JSON), and DOCX documents. Other file types are uploaded and stored but the AI cannot natively consume their contents, only use shell tools on them. |
+| `attachments` | Machine resources to focus the AI on, plus local files to upload (`File`, `Blob`, or `{ data, contentType, filename? }`). Pass object resources (`/space/...`) for object context and file resources (`/rool-drive/...`) for existing WebDAV files/folders. Local files are uploaded to authenticated space file storage first. The interaction stores canonical `rool-machine:/...` refs for UI rendering. The AI can interpret images (JPEG, PNG, GIF, WebP, SVG), PDFs, text-based files (plain text, Markdown, CSV, HTML, XML, JSON), and DOCX documents. Other file types are stored but the AI cannot natively consume their contents, only use shell tools on them. |
 | `signal` | `AbortSignal` to stop the prompt mid-flight. When aborted, the agent loop halts and the streaming response closes. Note that any LLM turn already in flight on Vertex keeps generating server-side and is billed. |
 
 ### Effort Levels
@@ -470,9 +463,12 @@ const { objects } = await channel.prompt(
 );
 
 // Work with specific objects
+const intro = resolveMachineResource('/space/article/intro.json');
+const conclusion = resolveMachineResource('/space/article/conclusion.json');
+if (!intro || !conclusion) throw new Error('invalid resource');
 const result = await channel.prompt(
   "Summarize these articles",
-  { locations: ['/space/article/intro.json', '/space/article/conclusion.json'] }
+  { attachments: [intro, conclusion] }
 );
 
 // Quick question without mutations (fast model + read-only)
@@ -487,11 +483,13 @@ await channel.prompt(
   { effort: 'REASONING' }
 );
 
-// Attach files for the AI to see (File from <input>, Blob, or base64)
+// Attach existing WebDAV files/folders or local uploads
+const report = resolveMachineResource('/rool-drive/docs/report.pdf');
+if (!report) throw new Error('invalid resource');
 const file = fileInput.files[0]; // from <input type="file">
 await channel.prompt(
-  "Describe what's in this photo and create an object for it",
-  { attachments: [file] }
+  "Compare this report with the uploaded photo",
+  { attachments: [report, file] }
 );
 
 // Cancel a long-running prompt
@@ -508,12 +506,18 @@ await channel.prompt("Do a deep analysis...", {
 Use `responseSchema` to get structured JSON instead of a text message:
 
 ```typescript
+const resources = [
+  '/space/item/widget.json',
+  '/space/item/gadget.json',
+  '/space/item/gizmo.json',
+].map((path) => {
+  const resource = resolveMachineResource(path);
+  if (!resource) throw new Error(`invalid resource: ${path}`);
+  return resource;
+});
+
 const { message } = await channel.prompt("Categorize these items", {
-  locations: [
-    '/space/item/widget.json',
-    '/space/item/gadget.json',
-    '/space/item/gizmo.json',
-  ],
+  attachments: resources,
   responseSchema: {
     type: 'object',
     properties: {
@@ -535,7 +539,7 @@ console.log(result.categories, result.summary);
 AI operations automatically receive context:
 - **Interaction history** — Previous interactions and their results from this channel
 - **Recently modified objects** — Objects created or changed recently
-- **Selected objects** — Objects passed via `locations` are given primary focus
+- **Attached resources** — Object resources passed via `attachments` are given primary focus; file resources are surfaced as `/rool-drive/...` paths
 
 This context flows automatically — no configuration needed. The AI sees enough history to maintain coherent interactions while respecting the `_`-prefixed field hiding rules.
 
@@ -564,7 +568,7 @@ await space.addUser(user.id, 'editor');
 | `owner` | Full control, can delete space and manage all users |
 | `admin` | All editor capabilities, plus can manage users (except other admins/owners) |
 | `editor` | Can create, modify, move, and delete objects |
-| `viewer` | Read-only access (can query with `prompt` and `findObjects`) |
+| `viewer` | Read-only access (can query with `prompt` and read objects/files) |
 
 ### Space Collaboration Methods
 
@@ -611,18 +615,9 @@ When a user accesses a space via URL, they're granted the corresponding role (`v
 
 ### Real-time Collaboration
 
-When multiple users have a space open, changes sync in real-time. The `source` field in events tells you who made the change:
+When multiple users have a space open, object and file changes are announced by `space.on('filesChanged')` and reconciled through WebDAV `syncCollection()`. Channel/conversation state still emits channel events; filesystem state does not use channel object events.
 
-```typescript
-channel.on('objectUpdated', ({ location, object, source }) => {
-  if (source === 'remote_user') {
-    // Another user made this change
-    showCollaboratorActivity(object);
-  }
-});
-```
-
-See [Real-time Sync](#real-time-sync) for more on event sources.
+See [Real-time Sync](#real-time-sync) for a WebDAV sync-token example.
 
 ## RoolClient API
 
@@ -653,8 +648,6 @@ const client = new RoolClient({
 | `duplicateSpace(sourceSpaceId, name): Promise<RoolSpace>` | Duplicate an existing space. Returns a handle to the new space. |
 | `deleteSpace(id): Promise<void>` | Permanently delete a space (cannot be undone) |
 | `importArchive(name, archive): Promise<RoolSpace>` | Import from a zip archive, creating a new space |
-| `webdav(spaceId): RoolWebDAV` | Open a WebDAV client for a space's file storage |
-| `getSpaceStorageUsage(spaceId): Promise<SpaceFileStorageUsage>` | Get WebDAV quota usage for a space |
 
 ### Channel Management
 
@@ -663,7 +656,6 @@ Manage channels on the `RoolSpace` handle:
 | Method | Description |
 |--------|-------------|
 | `space.channels: ChannelInfo[]` | Live channel list (auto-updates via SSE) |
-| `space.getChannels(): ChannelInfo[]` | List channels (deprecated — use `space.channels` instead) |
 | `space.renameChannel(channelId, name): Promise<void>` | Rename a channel |
 | `space.deleteChannel(channelId): Promise<void>` | Delete a channel and its interaction history |
 | `channel.rename(name): Promise<void>` | Rename the current open channel |
@@ -707,39 +699,11 @@ client.on('userStorageChanged', ({ key, value, source }) => {
 });
 ```
 
-### Extensions
-
-Manage and publish extensions. See [`@rool-dev/extension`](/extension/) for building extensions.
-
-There are two distinct domains: your **personal library** (extensions you've created or installed) and the **published extensions** (extensions discoverable by all users). Each has its own return type.
-
-#### Your Library (`ExtensionInfo`)
-
-Manage extensions you own. Each `ExtensionInfo` includes `published` (whether it's listed in the marketplace) and `marketplaceExtensionId` (non-null if you installed it from someone else's listing, null if you authored it).
-
-| Method | Description |
-|--------|-------------|
-| `uploadExtension(extensionId, options): Promise<ExtensionInfo>` | Upload or update an extension (`options.bundle`: zip with `index.html` and `manifest.json`) |
-| `listExtensions(): Promise<ExtensionInfo[]>` | List your extensions |
-| `getExtensionInfo(extensionId): Promise<ExtensionInfo \| null>` | Get info for a specific extension |
-| `deleteExtension(extensionId): Promise<void>` | Delete an extension permanently (removes files and DB row) |
-
-#### Marketplace (`PublishedExtensionInfo`)
-
-Discover and install extensions published by other users.
-
-| Method | Description |
-|--------|-------------|
-| `findExtensions(options?): Promise<PublishedExtensionInfo[]>` | Search the marketplace. Options: `query` (semantic search string), `limit` (default 20, max 100). Omit `query` to browse all. |
-| `publishToPublic(extensionId): Promise<void>` | Publish one of your extensions to the marketplace |
-| `unpublishFromPublic(extensionId): Promise<void>` | Remove from the marketplace (keeps the extension in your library) |
-
 ### Utilities
 
 | Method | Description |
 |--------|-------------|
-| `RoolClient.generateBasename(): string` | Generate a 6-char alphanumeric basename for new object identities. |
-| `RoolClient.generateId(): string` | Same as `generateBasename()`; retained for callers minting non-object IDs (interactions, conversations, channels). |
+| `RoolClient.generateId(): string` | Generate a unique 6-character alphanumeric ID. |
 | `destroy(): void` | Clean up resources |
 
 ### Client Events
@@ -801,10 +765,8 @@ A space handle with a live SSE subscription. Extends `EventEmitter`. Manages use
 | `addUser(userId, role): Promise<void>` | Add user to space |
 | `removeUser(userId): Promise<void>` | Remove user from space |
 | `setLinkAccess(linkAccess): Promise<void>` | Set URL sharing level |
-| `getChannels(): ChannelInfo[]` | List channels (deprecated — use `channels` property instead) |
 | `renameChannel(channelId, name): Promise<void>` | Rename a channel |
 | `deleteChannel(channelId): Promise<void>` | Delete a channel |
-| `installExtension(extensionId, channelId): Promise<string>` | Install an extension into a channel of this space. If you own it, wires it directly. If it's a marketplace extension, copies and builds a new extension in your library. Returns the channel ID. |
 | `exportArchive(): Promise<Blob>` | Export space as zip archive |
 | `getStorageUsage(): Promise<SpaceFileStorageUsage>` | Get WebDAV quota usage for this space |
 | `fetchMachineResource(resource): Promise<Response>` | Fetch a resolved file `MachineResource` through this space |
@@ -814,8 +776,9 @@ A space handle with a live SSE subscription. Extends `EventEmitter`. Manages use
 
 ```typescript
 space.on('channelCreated', (channel: ChannelInfo) => void)   // New channel added
-space.on('channelUpdated', (channel: ChannelInfo) => void)   // Channel metadata changed (name, extension, manifest)
+space.on('channelUpdated', (channel: ChannelInfo) => void)   // Channel metadata changed
 space.on('channelDeleted', (channelId: string) => void)      // Channel removed
+space.on('filesChanged', ({ source, timestamp }) => void)     // WebDAV file storage changed; call webdav.syncCollection()
 space.on('connectionStateChanged', (state: 'connected' | 'disconnected' | 'reconnecting') => void)
 ```
 
@@ -834,9 +797,6 @@ 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 |
-| `extensionUrl: string \| null` | URL of the installed extension, or null if this is a plain channel |
-| `extensionId: string \| null` | ID of the installed extension, or null if this is a plain channel |
-| `manifest: ExtensionManifest \| null` | Extension manifest snapshot (name, icon, collections, etc.), or null |
 
 ### Lifecycle
 
@@ -856,8 +816,6 @@ All methods that accept a location accept either the canonical form or the short
 |--------|-------------|
 | `getObject(location): Promise<RoolObject \| undefined>` | Get an object, or undefined if not found. |
 | `stat(location): RoolObjectStat \| undefined` | Get audit info for an object: when it was last modified, by whom, and where (channel/conversation/interaction). Sync read from local cache. |
-| `findObjects(options): Promise<{ objects, message }>` | Find objects using structured filters and/or natural language. Results sorted by modifiedAt (desc by default). |
-| `getObjectLocations(options?): string[]` | Get all object locations. Sorted by modifiedAt (desc by default). Options: `{ limit?, order? }`. |
 | `createObject(collection, body, options?): Promise<{ object, message }>` | Create a new object in `collection`. The SDK mints a random basename unless you pass `options.basename`. |
 | `updateObject(location, options): Promise<{ object, message }>` | Update an existing object's body. |
 | `moveObject(from, to, options?): Promise<{ object, message }>` | Rename or relocate an object. See [Moving and Renaming](#moving-and-renaming). |
@@ -950,59 +908,6 @@ await channel.moveObject(from, to, {
 | `ephemeral` | If true, the operation won't be recorded in interaction history. |
 | `parentInteractionId` | Conversation tree parent. Omit to auto-continue; pass `null` for a new root. |
 
-#### findObjects
-
-Find objects using structured filters and/or natural language.
-
-- **`where` only** — exact-match filtering, no AI, no credits.
-- **`collection` only** — filter by collection name, no AI, no credits.
-- **`prompt` only** — AI-powered semantic query over all objects.
-- **`where` + `prompt`** — `where` (and `locations`) narrow the data set first, then the AI queries within the constrained set.
-
-| Option | Description |
-|--------|-------------|
-| `where` | Exact-match body-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. |
-| `collection` | Filter by collection name. |
-| `prompt` | Natural language query. Triggers AI evaluation (uses credits). |
-| `limit` | Maximum number of results. |
-| `locations` | Scope to specific object locations. Constrains the candidate set in both structured and AI queries. |
-| `order` | Sort order by modifiedAt: `'asc'` or `'desc'` (default: `'desc'`). |
-| `ephemeral` | If true, the query won't be recorded in interaction history. Useful for responsive search. |
-
-**Examples:**
-
-```typescript
-// Filter by collection (no AI, no credits)
-const { objects } = await channel.findObjects({
-  collection: 'article'
-});
-
-// Exact field matching (no AI, no credits)
-const { objects } = await channel.findObjects({
-  where: { status: 'published' }
-});
-
-// Combine collection and field filters
-const { objects } = await channel.findObjects({
-  collection: 'article',
-  where: { status: 'published' }
-});
-
-// Pure natural language query (AI interprets)
-const { objects, message } = await channel.findObjects({
-  prompt: 'articles about space exploration published this year'
-});
-
-// Combined: collection + where narrow the data, prompt queries within it
-const { objects } = await channel.findObjects({
-  collection: 'article',
-  prompt: 'that discuss climate solutions positively',
-  limit: 10
-});
-```
-
-When `where` or `locations` are provided with a `prompt`, the AI only sees the filtered subset — not the full space. The returned `message` explains the query result.
-
 ### Undo/Redo
 
 | Method | Description |
@@ -1030,12 +935,13 @@ Store arbitrary data alongside the space without it being part of an object's bo
 
 Every space has authenticated file storage. WebDAV is the SDK surface for that storage: paths are relative to the space root and collection operations use WebDAV collection semantics. Human/AI file links use `rool-machine:/rool-drive/...`; resolve those links with `resolveMachineResource()` and fetch file resources with `space.fetchMachineResource(resource)`.
 
-Use `client.webdav(spaceId)` when you only have an ID, or `space.webdav` when you already have an open space.
+Open a space, then use `space.webdav`.
 
 ```typescript
 import { resolveMachineResource } from '@rool-dev/sdk';
 
-const webdav = client.webdav('space-id');
+const space = await client.openSpace('space-id');
+const webdav = space.webdav;
 
 await webdav.mkcol('docs');
 await webdav.put('docs/readme.md', '# Hello', {
@@ -1059,19 +965,33 @@ const usage = await space.getStorageUsage();
 console.log(usage.usedBytes);
 console.log(usage.availableBytes); // null means unlimited
 console.log(usage.limitBytes);     // null means unlimited
+
+const rootProps = await webdav.propfind('', {
+  depth: '0',
+  props: ['sync-token', 'supported-report-set'],
+});
+let syncToken = rootProps.responses[0]?.props.syncToken ?? null;
+
+space.on('filesChanged', async () => {
+  const delta = await space.webdav.syncCollection('', {
+    token: syncToken,
+    level: 'infinite',
+  });
+  syncToken = delta.token;
+  console.log('Changed file responses:', delta.responses);
+});
 ```
 
 Paths are space-relative (`docs/readme.md`, not `/docs/readme.md`). WebDAV methods accept WebDAV paths only. User-facing file links should use `rool-machine:/rool-drive/...`; resolve either that URI or a bare `/rool-drive/...` machine path with `resolveMachineResource()` and fetch the resulting file resource with `space.fetchMachineResource(resource)`. `PUT` writes an exact path and does not create parent collections; create parents with `mkcol()` first. Helpers preserve WebDAV status semantics: non-success responses throw `WebDAVError` with `status`, `statusText`, and `body`.
 
 | Method | Description |
 |--------|-------------|
-| `client.webdav(spaceId)` | Create a WebDAV client for a space |
-| `client.getSpaceStorageUsage(spaceId)` | Get WebDAV quota usage for a space |
 | `space.webdav` | WebDAV client for an open space |
 | `space.getStorageUsage()` | Get WebDAV quota usage for an open space |
 | `webdav.getStorageUsage()` | Get WebDAV quota usage through the WebDAV client |
 | `webdav.path(path)` | Normalize a WebDAV path |
-| `webdav.propfind(path, options)` | Read properties/list collections; explicit `depth` required |
+| `webdav.propfind(path, options)` | Read properties/list collections; explicit `depth` required. Supports `sync-token` and `supported-report-set` props. |
+| `webdav.syncCollection(path, options)` | Reconcile WebDAV changes with `REPORT sync-collection`. Pass the previous `token` (or `null`), `level: '1' \| 'infinite'`, optional `props`/`limit`; returns changed responses plus the next `token`. |
 | `webdav.get(path, options?)` / `webdav.head(path)` | Read a file, including optional byte ranges for `get` |
 | `webdav.put(path, body, options?)` | Write an exact file path; parents must already exist |
 | `webdav.mkcol(path)` | Create one collection |
@@ -1198,37 +1118,23 @@ The archive bundles `data.json` (objects, metadata, and channels) together with
 
 ### Channel Events
 
-Semantic events describe what changed. Events fire for both local changes and remote changes.
+Channel events are for channel/conversation state. Object and file reactivity goes through `space.on('filesChanged' | 'filesReset')` plus WebDAV `syncCollection()`.
 
 ```typescript
-// source indicates origin:
-// - 'local_user': This client made the change
-// - 'remote_user': Another user/client made the change
-// - 'remote_agent': AI agent made the change
-// - 'system': Resync after error
-
-// Object events — payload includes the full RoolObject
-channel.on('objectCreated', ({ location, object, source }) => void)
-channel.on('objectUpdated', ({ location, object, source }) => void)
-channel.on('objectDeleted', ({ location, source }) => void)
-channel.on('objectMoved',   ({ from, to, object, source }) => void)
-
-// Space metadata
-channel.on('metadataUpdated', ({ metadata, source }) => void)
-
-// Collection schema changed
-channel.on('schemaUpdated', ({ schema, source }) => void)
-
-// Channel metadata updated (name, extensionUrl)
+// Channel metadata updated
 channel.on('channelUpdated', ({ channelId, source }) => void)
 
 // Conversation interaction history updated
 channel.on('conversationUpdated', ({ conversationId, channelId, source }) => void)
 
+// Space metadata / schema compatibility events
+channel.on('metadataUpdated', ({ metadata, source }) => void)
+channel.on('schemaUpdated', ({ schema, source }) => void)
+
 // Full state replacement (undo/redo, resync after error)
 channel.on('reset', ({ source }) => void)
 
-// Sync error occurred, channel resynced from server
+// Sync error occurred
 channel.on('syncError', (error: Error) => void)
 ```
 
@@ -1359,13 +1265,10 @@ interface Channel {
   createdAt: number;            // Timestamp when channel was created
   createdBy: string;            // User ID who created the channel
   createdByName?: string;       // Display name at time of creation
-  extensionUrl?: string;        // URL of installed extension (set by installExtension)
-  extensionId?: string;         // ID of installed extension (user_extensions.extension_id)
-  manifest?: ExtensionManifest; // Extension manifest snapshot (set when extension is wired)
   conversations: Record<string, Conversation>;  // Keyed by conversation ID
 }
 
-// Channel summary info (returned by client.getChannels)
+// Channel summary info (used by space.channels)
 interface ChannelInfo {
   id: string;
   name: string | null;
@@ -1373,9 +1276,6 @@ interface ChannelInfo {
   createdBy: string;
   createdByName: string | null;
   interactionCount: number;
-  extensionUrl: string | null;  // URL of installed extension, or null
-  extensionId: string | null;   // ID of installed extension, or null
-  manifest: ExtensionManifest | null;  // Extension manifest snapshot, or null
 }
 ```
 
@@ -1414,7 +1314,7 @@ interface Interaction {
   ai: boolean;                             // Whether AI was invoked (vs synthetic confirmation)
   modifiedObjectLocations: string[];       // Locations of objects affected by this interaction
   toolCalls: ToolCall[];                   // Tools called during this interaction (for AI prompts)
-  attachments?: string[];                  // rool-machine:/rool-drive/... file references attached by the user
+  attachments?: string[];                  // canonical rool-machine:/... resource refs attached by the user
 }
 ```
 
@@ -1435,15 +1335,15 @@ type ChangeSource = 'local_user' | 'remote_user' | 'remote_agent' | 'system';
 
 ```typescript
 type PromptEffort = 'QUICK' | 'STANDARD' | 'REASONING' | 'RESEARCH';
+type PromptAttachment = File | Blob | { data: string; contentType: string; filename?: string } | MachineResource;
 
 interface PromptOptions {
-  locations?: string[];                                                  // Scope to specific objects
   responseSchema?: Record<string, unknown>;
   effort?: PromptEffort;                                                 // Effort level (default: 'STANDARD')
   ephemeral?: boolean;                                                   // Don't record in interaction history
   readOnly?: boolean;                                                    // Disable mutation tools (default: false)
   parentInteractionId?: string | null;                                   // Branch from a specific interaction (omit to auto-continue)
-  attachments?: Array<File | Blob | { data: string; contentType: string }>; // Files to attach
+  attachments?: PromptAttachment[];                                      // Machine resources or local files to upload
   signal?: AbortSignal;                                                  // Cancel an in-flight prompt
 }
 ```