drafted 1.24.2 → 1.24.3

package/mcp/server.mjs

@@ -485,6 +485,7 @@ const TOOL_ANNOTATIONS = {
 
   // Canvas / view
   mail:                { title: 'Connected email threads', readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Connect a Gmail thread to a project so a reply to it is noticed. Drafted never reads mail: the user\'s own computer checks connected threads with their read-only gws sign-in and tells Drafted only that a new message arrived. Dispatch by `action`: connect (project, gmailThreadId, title, onReply), list (project), set (id, onReply/title), handled (id: clear the New reply mark after you dealt with it), disconnect (id). onReply: notify = mark it and tell the user; work = also start the user\'s agent on it. Read the thread itself with gws, and send any reply with action(propose, type="send_email").' },
+  frame_db:            { title: 'Frame documents',      readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Read and write an app frame\'s documents — the same store the frame\'s own JavaScript uses through `drafted.db`. Dispatch by `action`: list, get, set, merge, delete. Documents are addressed by (frame, collection, id); a write can carry `expectedUpdatedAt` so a stale write is refused instead of overwriting. Authorization is the frame\'s own: access to the frame, edit access for writes, and the `db` capability its author granted.' },
   focus:               { title: 'Focus on target',     readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Pan the canvas viewport for connected clients to a frame, lane, or layer.' },
   tour:                { title: 'Guided tours',        readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Play or stop an agent-authored guided tour (driver.js) on the project surface for all connected clients. Tours live on a frame\'s metadata.tour — author them with fs(write, metadata={tour: {title, steps}}). Dispatch by `action`: play (frameId) starts the walkthrough, stop (projectId) ends it. Use for presentations and collaborative walkthroughs.' },
   screenshot:          { title: 'Screenshot',          readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'Render a PNG via headless browser. `scope=frame` for a single frame, `scope=canvas` for a region of the project surface.' },
@@ -3083,6 +3084,80 @@ tool('mail', {
   } catch (error) { return err(error); }
 });
 
+tool('frame_db', `Read and write an app frame's documents — the same store the frame's own JavaScript uses through \`drafted.db\`.
+
+An app frame has a document store now (collection → document, one document per row of whatever the app shows). This tool is the agent's side of it: seeding a list, reading what the team has recorded, correcting a row. Before it existed the store was reachable only from the frame's own code or a raw authenticated HTTP call.
+
+Authorization is the frame's own: the caller must have access to the frame, writes need edit access, and the frame's author must have granted the \`db\` capability. A read-only share can READ (the data is what they were invited to look at) and is refused on writes.
+
+Actions:
+  list    — documents in one collection (limit/offset, ordered by updatedAt or id)
+  get     — one document
+  set     — replace one document's data (creates it)
+  merge   — shallow-merge fields into one document
+  delete  — remove one document
+
+\`expectedUpdatedAt\` is optimistic concurrency: pass the document's updatedAt as you last read it and a stale write is refused with code \`conflict\` plus the current document, instead of silently overwriting somebody's change. Omit it for a blind write.`, {
+  action: z.enum(['list', 'get', 'set', 'merge', 'delete']).describe('the operation'),
+  target: z.string().describe('the frame: its URL (…/o/<org>/projects/<project>/<layer>/<lane>/<file>), a /projects path, or a frame UUID'),
+  collection: z.string().describe('the collection name, e.g. "tracking" — letters, digits and _ . : - only'),
+  id: z.string().optional().describe('document id, required for get/set/merge/delete'),
+  data: z.any().optional().describe('[set/merge] the document body: plain JSON, at most 64KB. merge is a shallow merge, so nested objects are replaced, not merged'),
+  expectedUpdatedAt: z.string().optional().describe("the document updatedAt as you last read it; a stale write is refused with code \"conflict\" rather than overwriting"),
+  limit: z.number().int().min(1).max(500).optional().describe('[list] page size (default 100, max 500)'),
+  offset: z.number().int().min(0).optional().describe('[list] page offset — the cursor for walking a large collection'),
+  orderBy: z.enum(['updatedAt', 'id']).optional().describe('[list] ordering key (default updatedAt)'),
+  dir: z.enum(['asc', 'desc']).optional().describe('[list] direction (default desc)'),
+}, async (args) => {
+  const { action, target, collection, id, data, expectedUpdatedAt, limit, offset, orderBy, dir } = args;
+  if (!target) return err(new Error('frame_db needs a target: the frame URL, /projects path, or frame id'));
+  if (!collection) return err(new Error('frame_db needs a collection'));
+
+  // The org is in the target when the target is a path; a bare UUID has none and
+  // resolves in the session's org. Same rule as fs: the address carries the scope.
+  const orgInTarget = (String(target).match(/\/o\/([^/]+)\//) || [])[1] || null;
+  const orgHeader = orgInTarget ? { 'X-Drafted-Org': decodeURIComponent(orgInTarget) } : {};
+
+  let frameId;
+  try {
+    ({ frameId } = await resolveFsFramePath(target));
+  } catch (e) {
+    return err(new Error(`${e.message}${orgInTarget ? '' : ' — include the /o/<org>/… URL when the frame is not in the workspace you are working in'}`));
+  }
+
+  const base = `/api/frame-runtime/${frameId}/db/${encodeURIComponent(collection)}`;
+  const q = [];
+  if (limit != null) q.push('limit=' + limit);
+  if (offset != null) q.push('offset=' + offset);
+  if (orderBy) q.push('orderBy=' + encodeURIComponent(orderBy));
+  if (dir) q.push('dir=' + encodeURIComponent(dir));
+  const qs = q.length ? '?' + q.join('&') : '';
+
+  try {
+    if (action === 'list') {
+      const res = await api('GET', base + qs, undefined, orgHeader);
+      return ok(res);
+    }
+    if (!id) return err(new Error(`frame_db ${action} needs a document id`));
+    const docPath = `${base}/${encodeURIComponent(id)}`;
+    if (action === 'get') return ok(await api('GET', docPath, undefined, orgHeader));
+    if (action === 'delete') return ok(await api('DELETE', docPath, undefined, orgHeader));
+    if (data === undefined) return err(new Error(`frame_db ${action} needs data`));
+    const res = await api(action === 'merge' ? 'PATCH' : 'PUT', docPath, { data, expectedUpdatedAt }, orgHeader);
+    return ok(res);
+  } catch (e) {
+    // A conflict carries the current document; a locked frame names the holder.
+    // Flattening either into "HTTP 409" would hide the thing the caller acts on.
+    if (e && (e.code === 'conflict' || e.code === 'locked' || e.code === 'quota_exceeded' || e.code === 'not_granted')) {
+      // api() attaches the parsed body: the conflict carries the CURRENT document
+      // and the lock carries its holder. Both are what the caller acts on.
+      const detail = e.body ? JSON.stringify(e.body).slice(0, 800) : '';
+      return err(new Error(`${e.code}: ${e.message}${detail ? ' — ' + detail : ''}`));
+    }
+    throw e;
+  }
+});
+
 tool('focus', {
   target: z.string().describe('What to pan the canvas to: a frame path (/projects/<project>/<layer>/<lane>/<file>), a frame URL (any URL containing /f/{uuid} or /o/<org>/projects/...), or a frame ID (UUID). When a user shares a Drafted link, pass it directly here.'),
 }, async ({ target }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.24.2",
+  "version": "1.24.3",
   "description": "Drafted — visual thinking surface for humans and AI agents. Renders HTML, markdown, images, and code as frames on a zoomable canvas, with MCP tools for AI agents and real-time sync for humans.",
   "type": "module",
   "bin": {