drafted 1.24.1 → 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.' },
@@ -1616,21 +1617,47 @@ async function pathOrgMatches(orgSegment, meta) {
   return !!hit && meta?.orgId === hit.id;
 }
 
-async function resolveProjectRef(ref) {
+/**
+ * Fetch /api/projects with NO org scope.
+ *
+ * api() otherwise stamps the session's working org on every request, so a
+ * listing meant to answer "which projects exist in the org this PATH names"
+ * came back scoped to the org the session happened to be working in, and the
+ * org filter then removed all of it. An empty header is how the server is told
+ * "unaddressed" (req.get('x-drafted-org') is falsy) without a server change.
+ */
+const NO_ORG_SCOPE = { 'X-Drafted-Org': '' };
+
+async function resolveProjectRef(ref, orgHint = null) {
   if (!ref) return null;
-  const hit = projectRefCache.get(ref);
+  const cacheKey = orgHint ? `${orgHint}|${ref}` : ref;
+  const hit = projectRefCache.get(cacheKey) || (!orgHint && projectRefCache.get(ref));
   if (hit) return hit;
-  const data = await api('GET', '/api/projects');
-  const list = Array.isArray(data?.projects) ? data.projects : [];
+  // Scope the lookup to the org the path named. Without a hint the session's
+  // org applies — which is right for `fs ls /projects` but WRONG for a path
+  // that addressed another org, and that mismatch is what made a project
+  // created in org B unresolvable from a session working in org A.
+  const scoped = orgHint ? await api('GET', '/api/projects', undefined, { 'X-Drafted-Org': orgHint }) : await api('GET', '/api/projects');
+  let list = Array.isArray(scoped?.projects) ? scoped.projects : [];
   const want = String(ref).toLowerCase();
-  const p =
-    list.find(x => x.id === ref) ||
-    list.find(x => String(x.slug || '').toLowerCase() === want) ||
-    list.find(x => String(x.name || '').toLowerCase() === want);
+  const pick = (rows) =>
+    rows.find(x => x.id === ref) ||
+    rows.find(x => String(x.slug || '').toLowerCase() === want) ||
+    rows.find(x => String(x.name || '').toLowerCase() === want);
+  let p = pick(list);
+  // A miss is worth one unscoped look before "not found": the hint may be stale
+  // (a project that moved org), and an id passed as projectId= carries no org at
+  // all — only a UUID can name a project in an org the session is not inside.
+  if (!p && (orgHint || /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(ref)))) {
+    const all = await api('GET', '/api/projects', undefined, NO_ORG_SCOPE);
+    list = Array.isArray(all?.projects) ? all.projects : [];
+    p = pick(list);
+  }
   if (!p) return null;
   // `folder` rides along so a caller can rebuild the project's printed address
   // (/o/<org>/projects/<folder>/<slug>) without a second lookup.
   const meta = { id: p.id, slug: p.slug || null, name: p.name || null, orgId: p.orgId || null, orgSlug: p.orgSlug || null, folder: p.folder || '' };
+  projectRefCache.set(cacheKey, meta);
   projectRefCache.set(ref, meta);
   projectRefCache.set(p.id, meta);
   return meta;
@@ -1645,13 +1672,15 @@ async function resolveProjectRef(ref) {
  *
  * One /api/projects fetch for the whole scan, not one per candidate.
  */
-async function resolveFolderQualifiedProject(parts) {
+async function resolveFolderQualifiedProject(parts, orgHint = null) {
   // NOT `.catch(() => null)`. Swallowing the fetch turns "the session is gated"
   // or "the server is down" into "project not found", which is a wrong DIAGNOSIS,
   // not just a lost detail — it sends you hunting for a project instead of
   // reading the gate. Observed once for real: an unnamed session after an MCP
   // restart reported `project not found: Marketing/beoflow-marketing`.
-  const data = await api('GET', '/api/projects');
+  // Same org rule as resolveProjectRef: a folder-qualified address names an org,
+  // so the lookup has to be made in it rather than in the working org.
+  const data = await api('GET', '/api/projects', undefined, orgHint ? { 'X-Drafted-Org': orgHint } : NO_ORG_SCOPE);
   const list = Array.isArray(data?.projects) ? data.projects : [];
   const norm = (s) => String(s || '').toLowerCase();
   for (let i = 1; i < parts.length; i++) {
@@ -3055,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 }) => {
@@ -3342,6 +3445,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
   title: z.string().optional().describe('[write + googleType] title for a new native file'),
   ops: z.array(z.any()).optional().describe('[edit] hashline ops for text frames. Apply ONLY against a fresh fs(read) of the frame: each op = {type, lineHash, newContent} where type is one of replace | delete | insertAfter | insertBefore, and lineHash is the FULL anchor from the read output (line number + hash, e.g. the token left of the |, like 42srt) — NOT a bare hash. delete/replace consume the target line; at most one replace/delete per line per edit (combine into one replace). If an op targets a line that changed since read it is rejected — re-read and retry. Element ops for excalidraw ({id,x,y,...}), or structured ops for office'),
   state: z.any().optional().describe('[write] app-frame state (JSON) to persist for a deployed windowType:"app" frame; the canvas hydrates the app from it on load. Max 64KB.'),
+  expectedUpdatedAt: z.string().optional().describe('[write] optimistic concurrency: the frame\'s updatedAt as you last read it. If somebody else wrote since, the write is refused with code "conflict" and the current version, instead of silently overwriting their change. Omit for a blind write.'),
   metadata: z.any().optional().describe('[write] JSON metadata to attach to the written frame (e.g. {"tour": {title, auto?, steps}} to define a guided tour on this frame). Max 64KB.'),
   readme: z.string().optional().describe('[write] README.md markdown for a skill at /o/<org>/skills/<slug> — optional on both create and update. Stored as a supporting skill file so the skill directory renders a landing page on GitHub when exported; a skill created without one is returned with a warning, never rejected. Equivalent to a later fs(write, path="/o/<org>/skills/<slug>/README.md").'),
   position: z.number().int().min(0).optional().describe('[mv] on a LAYER path, no `to`: move the layer to this 0-based index in the project\'s layer order (0 = first; `ls` of the project shows the order). A layer born from a first write is appended last, so use this to pin one first.'),
@@ -3353,7 +3457,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
   org: z.string().optional().describe('Org (id or name) for bare /wiki and /skills paths (org-scoped /o/<org>/... paths don\'t need it). Per-request only; project paths self-derive org from the project row.'),
   projectId: PROJECT_OVERRIDE_PARAM,
 }, async (args) => {
-  const { action, path: rawPath, to: rawTo, query, content, file_path, base64, googleType, title, ops, state, metadata, readme, recursive, pattern, lines, org } = args;
+  const { action, path: rawPath, to: rawTo, query, content, file_path, base64, googleType, title, ops, state, metadata, expectedUpdatedAt, readme, recursive, pattern, lines, org } = args;
   // Org-scoped path (Shape A): /o/<org>/<root>/... — strip the org segment here,
   // carry it as the per-request org scope (orgHeader), validate per-root below.
   // The PATH is the address; the org= param is legacy for bare roots only, and a
@@ -3631,7 +3735,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
     // (/o/<org>/projects/eng/x). The chain wins when both are given.
     const projectFolder = folder || (parts.length === 2 ? parts[0] : null);
     const projectRef = parts[parts.length - 1];
-    const existing = await resolveProjectRef(projectRef).catch(() => null);
+    const existing = await resolveProjectRef(projectRef, orgFromPath || org || null).catch(() => null);
     if (existing) return err(new Error(`project already exists: ${projectRef}`));
     const projectName = projectRef.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
     const created = await api('POST', '/api/projects', { name: projectName, ...(projectFolder ? { folder: projectFolder } : {}) }, orgHeader);
@@ -3925,7 +4029,14 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
       // Archived projects live in the Archive bin and are hidden from the agent's
       // active list — mirroring the web UI. An org-scoped root lists ONLY that
       // org's projects (Shape A).
-      const listing = await api('GET', '/api/projects');
+      //
+      // Fetch in the org the PATH names, not the one this session happens to be
+      // working in. api() stamps the working org on every request, so the
+      // unfiltered call came back as the working org's projects and the org
+      // filter below then removed every one of them: `ls /o/<other-org>/projects`
+      // answered "no projects" for an org with 265. Unscoped when the path names
+      // no org, which is what makes `/projects` the whole inventory again.
+      const listing = await api('GET', '/api/projects', undefined, orgFromPath ? { 'X-Drafted-Org': orgFromPath } : NO_ORG_SCOPE);
       let rows = (Array.isArray(listing?.projects) ? listing.projects : []).filter(x => !isTrashedRow(x));
       if (orgFromPath) {
         const kept = [];
@@ -4014,9 +4125,11 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
     // every failure as "project not found", so a gated session or an unreachable
     // server reads as a missing project.
     let lookupError = null;
-    let pathProject = await resolveProjectRef(projectRef).catch((e) => { lookupError = e; return null; });
+    // The org from the path rides the lookup: without it a project in another
+    // org was invisible and every write to it answered "project not found".
+    let pathProject = await resolveProjectRef(projectRef, orgFromPath || org || null).catch((e) => { lookupError = e; return null; });
     if (!pathProject?.id && parts.length > 1) {
-      const found = await resolveFolderQualifiedProject(parts);
+      const found = await resolveFolderQualifiedProject(parts, orgFromPath || org || null);
       if (found) { projectRef = parts[found.index]; tail = parts.slice(found.index + 1); pathProject = found.meta; }
     }
     if (!pathProject?.id && lookupError) return err(lookupError);
@@ -4057,9 +4170,9 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
       const segs = clean.replace(/^projects\/?/, '').split('/').filter(Boolean);
       if (!segs.length) throw new Error('destination needs a project: /o/<org>/projects/<project>/...');
       let idx = 0;
-      let meta = await resolveProjectRef(segs[0]).catch(() => null);
+      let meta = await resolveProjectRef(segs[0], orgFromPath || org || null).catch(() => null);
       if (!meta?.id && segs.length > 1) {
-        const found = await resolveFolderQualifiedProject(segs);
+        const found = await resolveFolderQualifiedProject(segs, orgFromPath || org || null);
         if (found) { idx = found.index; meta = found.meta; }
       }
       if (!meta?.id) throw new Error(`destination project not found: ${segs.join('/')} — list projects with fs(ls, path="/o/<org>/projects")`);
@@ -4215,6 +4328,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
           else if (base64) body.base64 = base64;
           else return err(new Error('write requires one of content / file_path / base64 / googleType / state'));
           if (metadata !== undefined) body.metadata = metadata;
+          if (expectedUpdatedAt) body.expectedUpdatedAt = expectedUpdatedAt;
           const result = await api('PUT', `/api/fs/${filePath}`, body, orgHeader);
           if (state !== undefined && result?.id) {
             try { await api('POST', `/api/file/${result.id}/state`, { state }); } catch { /* state best-effort */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.24.1",
+  "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": {