drafted 1.14.5 → 1.14.6

package/mcp/server.mjs

@@ -169,6 +169,22 @@ function scrubLocalPathMentions(description) {
 // inside the factory so each HTTP request gets its own isolated server.
 // Stdio mode uses the `mcpServer` singleton (built once at module load).
 
+// ── Org-ambiguity policy (the one decision core) ─────────────────
+// The org guard inside the factory plumbs session/HTTP state into this
+// side-effect-free predicate, which IS the policy (DRAFT-36 "one rule"). Top-level
+// + exported so the truth table can be asserted in isolation (mcp/test-org-guards.mjs).
+// It governs BOTH creates and forks (a fork is a create): a write proceeds when its
+// org is a real root — an explicit org=, a bound/active project, or a single-org
+// user's only org — and refuses to GUESS only when the user is multi-org with
+// nothing bound. A bound project is honored deliberately (Reading A): the active
+// project is the one legitimately-kept addressing root, NOT the deleted session
+// cursor. Awareness of a surprising destination (e.g. a fork) comes from the
+// response receipt naming the org (orgEcho), not from hard-blocking the flow.
+export function projectlessMutationNeedsOrg({ explicitOrg, boundOrgId, activeProjectId, isRemote, orgCount }) {
+  if (explicitOrg || boundOrgId || activeProjectId || isRemote) return false;
+  return (orgCount || 0) > 1;
+}
+
 export function createMcpServer(transport) {
 // Remote transports (hosted HTTP MCP for claude.ai / ChatGPT) run on the
 // server, not the user's machine, so local-filesystem params like `file_path`
@@ -1327,18 +1343,12 @@ async function requireBoundOrgForProjectlessMutation(explicitOrg) {
     if (ctx?.id) sess.boundOrgId = ctx.id;
     return;
   }
-  let count = sess.cachedOrgCount;
-  if (count == null) {
-    try {
-      const d = await api('GET', '/api/orgs');
-      count = (d.orgs || d || []).length;
-      sess.cachedOrgCount = count;
-    } catch { return; } // can't determine membership — don't block a legit write
-  }
-  if (count > 1) {
+  const orgs = await getOrgList();
+  if (!orgs.length) return; // can't determine membership — don't block a legit write
+  if (projectlessMutationNeedsOrg({ orgCount: orgs.length })) {
     throw new Error(
       `Refusing to guess the org: no project is open and no explicit org was ` +
-      `given, but you belong to ${count} orgs — a project-less wiki/skill write ` +
+      `given, but you belong to ${orgs.length} orgs — a project-less wiki/skill write ` +
       `would land in whichever org the session inherited. Pass org=... on this ` +
       `call (org name or id), or open the relevant project first ` +
       `(project(action="open") — the org derives from the project).`
@@ -1346,6 +1356,46 @@ async function requireBoundOrgForProjectlessMutation(explicitOrg) {
   }
 }
 
+// The user's org list, cached per-session (30s TTL) — shared by the ambiguity
+// guards and the response org-echo so a mutation costs at most one /api/orgs hit.
+// Returns [] (not throw) on failure: callers treat "unknown membership" as
+// "don't block", matching the prior guard behavior.
+async function getOrgList() {
+  const sess = getSessionState();
+  if (sess.cachedOrgs && Date.now() - (sess.cachedOrgsTime || 0) < 30000) return sess.cachedOrgs;
+  try {
+    const d = await api('GET', '/api/orgs');
+    sess.cachedOrgs = (d.orgs || d || []).map(o => ({ id: o.orgId || o.id, name: o.orgName || o.name }));
+    sess.cachedOrgsTime = Date.now();
+  } catch { sess.cachedOrgs = sess.cachedOrgs || []; }
+  return sess.cachedOrgs;
+}
+
+
+// Build the agent-facing "receipt" for a mutation: the org it actually wrote to
+// (+ a URL handle when the result carries one), so an implicit org resolution is
+// visible in the response instead of opaque. Best-effort: returns {} on any
+// failure so it never breaks a successful write. Prefers the org id the server
+// put on the created/edited row, then the explicit org arg, then the session org.
+// This is the agent-facing half of the receipt spine (DRAFT-36 P1); the
+// human-facing card/notice (P4) consumes the same shape server-side.
+async function orgEcho(result, explicitOrg) {
+  try {
+    const orgs = await getOrgList();
+    let orgId = result?.orgId || result?.org_id || null;
+    if (!orgId && explicitOrg) {
+      const hit = orgs.find(o => o.id === explicitOrg || (o.name || '').toLowerCase() === String(explicitOrg).toLowerCase());
+      orgId = hit?.id || explicitOrg;
+    }
+    if (!orgId) { const ctx = await getCurrentOrgContext(); orgId = ctx?.id || null; }
+    if (!orgId) return {};
+    const receipt = { org: { id: orgId, name: orgs.find(o => o.id === orgId)?.name || null } };
+    const url = result?.url || result?.frameUrl || null;
+    if (url) receipt.url = url;
+    return { receipt };
+  } catch { return {}; }
+}
+
 async function getOrgSkills(orgId) {
   if (!orgId) return [];
   // No cache: gate freshness > the ~5ms HTTP roundtrip. Otherwise an attach
@@ -1912,12 +1962,15 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
         if (g3) return err(new Error(g3));
         const { name, description, templateSlug, org } = args;
         if (!name) throw new Error('name required for action=create');
+        // Don't silently create the project in whatever org the session inherited.
+        await requireBoundOrgForProjectlessMutation(org);
         const body = { name };
         if (description) body.description = description;
         if (templateSlug) body.templateSlug = templateSlug;
         // `org` targets a specific org without switching the active org.
         const createExtra = org ? { 'X-Drafted-Org': org } : {};
-        return ok(withProjectBreadcrumb(await api('POST', '/api/projects', body, createExtra)));
+        const created = await api('POST', '/api/projects', body, createExtra);
+        return ok({ ...withProjectBreadcrumb(created), ...(await orgEcho(created, org)) });
       }
       case 'update': {
         const { projectId, name, folder, description, layers } = args;
@@ -2037,10 +2090,13 @@ tool('template', 'Manage project templates in an org. Dispatch by `action`: list
       case 'create': {
         const { name, description, layers, skillSlugs, visibility } = args;
         if (!name || !description || !layers) throw new Error('name, description, layers required for action=create');
+        // Don't silently create the template in whatever org the session inherited.
+        await requireBoundOrgForProjectlessMutation(args.org);
         const body = { name, description, layers };
         if (Array.isArray(skillSlugs)) body.skillSlugs = skillSlugs;
         if (visibility) body.visibility = visibility;
-        return ok(await api('POST', '/api/templates', body, orgHeader));
+        const createdTpl = await api('POST', '/api/templates', body, orgHeader);
+        return ok({ ...createdTpl, ...(await orgEcho(createdTpl, args.org)) });
       }
       case 'update': {
         const { templateId, name, description, layers, skillSlugs, visibility } = args;
@@ -2052,7 +2108,8 @@ tool('template', 'Manage project templates in an org. Dispatch by `action`: list
         if (Array.isArray(skillSlugs)) body.skillSlugs = skillSlugs;
         if (visibility) body.visibility = visibility;
         if (Object.keys(body).length === 0) throw new Error('At least one field is required for action=update');
-        return ok(await api('PUT', `/api/templates/${templateId}`, body, orgHeader));
+        const updatedTpl = await api('PUT', `/api/templates/${templateId}`, body, orgHeader);
+        return ok({ ...updatedTpl, ...(await orgEcho(updatedTpl, args.org)) });
       }
       case 'delete': {
         const { templateId } = args;
@@ -2062,9 +2119,12 @@ tool('template', 'Manage project templates in an org. Dispatch by `action`: list
       case 'fork': {
         const { templateId, name } = args;
         if (!templateId) throw new Error('templateId required for action=fork');
+        // Forking creates a new template — same org rule as any create.
+        await requireBoundOrgForProjectlessMutation(args.org);
         const body = {};
         if (name) body.name = name;
-        return ok(await api('POST', `/api/templates/${templateId}/fork`, body, orgHeader));
+        const forkedTpl = await api('POST', `/api/templates/${templateId}/fork`, body, orgHeader);
+        return ok({ ...forkedTpl, ...(await orgEcho(forkedTpl, args.org)) });
       }
       default:
         throw new Error(`Unknown template action: ${action}`);
@@ -2412,7 +2472,8 @@ async function getCachedMcpUpdateMetadata() {
 
 
 tool('get_org', {
-  action: z.enum(['get', 'update_mcp']).optional().describe('Default: "get" returns your orgs, the default org, and Google Drive availability. Use "update_mcp" to get explicit installed stdio MCP update instructions. There is no org switching: org derives from the resource you address (projectId/pageId/skillId), and creates/searches take an explicit org param.'),
+  action: z.enum(['get', 'update_mcp', 'use']).optional().describe('Default: "get" returns your orgs, this session\'s resolved working org, and Google Drive availability. "use" (with org=) sets THIS session\'s working org — a per-session, per-request DEFAULT for project-less creates/forks. It is NOT the retired sticky cursor: it never overrides a UUID-addressed resource, an explicit org=, or an open project, and it is private to this session (never a shared server row). "update_mcp" returns installed stdio MCP update instructions.'),
+  org: z.string().optional().describe('[use] org id or name to set as this session\'s working-org default.'),
 }, async (args = {}) => {
   try {
     const action = args.action || 'get';
@@ -2422,6 +2483,30 @@ tool('get_org', {
       return ok(buildInstalledMcpUpdateInstructions(mcpUpdate));
     }
 
+    if (action === 'use') {
+      // P3 (DRAFT-36): the explicit per-session working-org. Symmetric with what a remote
+      // connection gets from its OAuth org — a stdio agent declares it here. Stored in
+      // THIS session's bucket only (never a shared server row), injected as X-Drafted-Org
+      // by api(), and only a DEFAULT: a UUID-addressed resource, an explicit org=, or an
+      // open project always win. In-memory (not persisted) so it can never clobber another
+      // process's boot state — the concurrency invariant holds by construction.
+      const want = (args.org || '').trim();
+      if (!want) throw new Error('org (id or name) required for action=use');
+      const orgs = await getOrgList();
+      const byId = orgs.find((o) => o.id === want);
+      const byName = orgs.filter((o) => (o.name || '').toLowerCase() === want.toLowerCase());
+      const hit = byId || (byName.length === 1 ? byName[0] : null);
+      if (!hit) {
+        const reason = byName.length > 1 ? `ambiguous org name "${want}"` : `not a member of org "${want}"`;
+        throw new Error(`${reason}. Your orgs: ${orgs.map((o) => o.name || o.id).join(', ') || '(none resolvable)'}`);
+      }
+      getSessionState().boundOrgId = hit.id;
+      return ok({
+        workingOrg: { id: hit.id, name: hit.name },
+        note: `Working org for this session is now "${hit.name}". Project-less creates/forks default here; a UUID-addressed resource, an explicit org=, or an open project still win. Not the retired switch — per-session and per-request, never a shared cursor.`,
+      });
+    }
+
     // Source of truth = the org this MCP process scopes requests to (what mutations
     // will actually hit). Each MCP process is independent — multiple agents can run
     // in parallel scoped to different orgs. /auth/me reads sessions.org_id directly.
@@ -2432,6 +2517,13 @@ tool('get_org', {
     const orgs = (data.orgs || data || []).map(o => ({ id: o.orgId || o.id, name: o.orgName || o.name }));
     const activeOrg = sessionOrgId ? (orgs.find(o => o.id === sessionOrgId) || null) : null;
 
+    // This session's WORKING org (P3): where project-less creates/forks land by default.
+    // It's the per-session boundOrgId — set by an open project, a get_org(action="use"),
+    // or (remote) the connection's org — not the shared session cursor. Announce it so an
+    // agent can self-verify without guessing (invariant: "announced, never opaque").
+    const workingOrgId = getSessionState().boundOrgId || null;
+    const workingOrg = workingOrgId ? (orgs.find(o => o.id === workingOrgId) || { id: workingOrgId, name: null }) : null;
+
     const googleDrive = await getGoogleDriveAvailability();
     const mcpUpdate = await getCachedMcpUpdateMetadata();
 
@@ -2444,13 +2536,14 @@ tool('get_org', {
     }
     return ok({
       activeOrg,
+      workingOrg,
       orgs,
       members: members.map(m => ({ id: m.userId, name: m.username, email: m.email, role: m.role })),
       googleDrive,
       mcpVersion: PACKAGE_VERSION,
       mcpUpdate,
       session: await sessionSurfaceBlock(),
-      note: "Org is derived from the resource you address: opening a project binds this agent session's context (org = the project's org), and UUIDs (pageId/skillId/projectId) self-derive. activeOrg is only the DEFAULT for calls that name no resource and pass no org param — to target a different org, pass org=... on the call (wiki write/search, skill add/update/fork/push/list, project create, template actions), never a switch. `session` is THIS agent's own surface identity — `session.name` is the human-readable tab name the user sees (use it to identify which agent you are); refresh it via whoami. Concurrent MCP sessions can operate on different orgs simultaneously. If googleDrive.connected is true, strongly prefer Google Workspace frames for docs, sheets, and slides.",
+      note: "Org is derived from the resource you address: opening a project binds this agent session's context (org = the project's org), and UUIDs (pageId/skillId/projectId) self-derive. `workingOrg` is where project-less creates/forks land by default — set it explicitly with get_org(action=\"use\", org=...) when you're multi-org and working project-less; a UUID/explicit org=/open project always wins. It is per-session and per-request, never a shared cursor or a switch. `session` is THIS agent's own surface identity — `session.name` is the human-readable tab name the user sees (use it to identify which agent you are); refresh it via whoami. Concurrent MCP sessions can operate on different orgs simultaneously. If googleDrive.connected is true, strongly prefer Google Workspace frames for docs, sheets, and slides.",
     });
   } catch (error) { return err(error); }
 });
@@ -3400,7 +3493,9 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
     // bound org (or explicit org=) when the user is multi-org. (DRAFT-36 Phase 4.)
     // UUID-first exception: update/remove addressed by a skillId derive their org
     // from the skill row server-side, so the bound-org gate is unnecessary.
-    if (['add', 'update', 'remove', 'push', 'fork', 'import'].includes(action)) {
+    // `fork` (and the fork-on-403 branch inside `update`) run the same guard at
+    // fork time, inside their cases — a fork is a create, governed by the one rule.
+    if (['add', 'update', 'remove', 'push', 'import'].includes(action)) {
       const byId = (action === 'update' || action === 'remove') && /^[a-f0-9-]{36}$/.test(args.skillId || '');
       if (!byId) await requireBoundOrgForProjectlessMutation(args.org);
     }
@@ -3478,7 +3573,8 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
         // org names where the skill is born (UUID-first model: org is explicit at
         // create) — without this the bound-org guard accepts org= but the write
         // would land in the session org anyway.
-        return ok(await api('POST', '/api/skills', body, org ? { 'X-Drafted-Org': org } : {}));
+        const addedSkill = await api('POST', '/api/skills', body, org ? { 'X-Drafted-Org': org } : {});
+        return ok({ ...addedSkill, ...(await orgEcho(addedSkill, org)) });
       }
       case 'update': {
         // Auto-fork-on-update (tool behavior): if the target is read-only (global/
@@ -3502,9 +3598,14 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
         if (Object.keys(body).length === 0) throw new Error('At least one field is required for action=update');
         try {
           const r = await api('PUT', `/api/skills/${id}`, body, extra);
-          return ok({ ...r, forked: false });
+          return ok({ ...r, forked: false, ...(await orgEcho(r, org)) });
         } catch (e) {
           if (e.code !== 'skill_read_only') throw e;
+          // Read-only skill → the update becomes a FORK (a create). Its org must be a
+          // real root: explicit org=, the active project, or a single-org user's only
+          // org — else, multi-org with nothing bound, error rather than guess. The
+          // receipt names the resulting org so a surprising fork is visible (Reading A).
+          await requireBoundOrgForProjectlessMutation(org);
           let forkId;
           try {
             forkId = (await api('POST', `/api/skills/${id}/fork`, {}, extra)).id;
@@ -3514,7 +3615,7 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
             forkId = (await api('GET', `/api/skills/slug/${ownSlug}`, undefined, extra)).id;
           }
           const r2 = await api('PUT', `/api/skills/${forkId}`, body, extra);
-          return ok({ ...r2, forked: true });
+          return ok({ ...r2, forked: true, ...(await orgEcho(r2, org)) });
         }
       }
       case 'remove': {
@@ -3530,8 +3631,12 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
         let id = skillId;
         if (!id && slugArg) { const s = await api('GET', `/api/skills/slug/${slugArg}`, undefined, extra); id = s.id; }
         if (!id) throw new Error('skillId or skill (slug) required for action=fork');
+        // Forking creates a new skill — same org rule as any create (explicit org=,
+        // active project, or single-org; else refuse to guess). Receipt names the org.
+        await requireBoundOrgForProjectlessMutation(org);
         try {
-          return ok(await api('POST', `/api/skills/${id}/fork`, {}, extra));
+          const forkedSkill = await api('POST', `/api/skills/${id}/fork`, {}, extra);
+          return ok({ ...forkedSkill, ...(await orgEcho(forkedSkill, org)) });
         } catch (e) {
           if (e.status === 409) return ok({ status: 'conflict', error: e.message }); // org already owns this slug
           throw e;
@@ -3551,7 +3656,7 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
         if (!Array.isArray(fileList) || fileList.length === 0) throw new Error('files[] (non-empty) or dir required for action=push');
         const pushed = await api('POST', `/api/skills/${id}/files/bulk`, { files: fileList, deleteMissing: !!deleteMissing }, extra);
         if (dir) { try { if (ensureSkillInstallIgnored(dir)) pushed.gitignored = '.skillinstall/'; } catch { /* best-effort */ } }
-        return ok(pushed);
+        return ok({ ...pushed, ...(await orgEcho(pushed, org)) });
       }
       case 'attach': {
         const { skillId } = args;

package/mcp/test-org-guards.mjs

@@ -0,0 +1,33 @@
+// Regression check for the MCP org-ambiguity policy (DRAFT-36 "one rule").
+// Run: `node mcp/test-org-guards.mjs`. No framework — asserts the single pure
+// decision core that the org guard delegates to, for BOTH creates and forks.
+import assert from 'node:assert/strict';
+import { projectlessMutationNeedsOrg } from './server.mjs';
+
+// One rule governs create AND fork (a fork is a create). A write proceeds when its
+// org is a real root — explicit org=, a bound/active project, a remote-adopted org,
+// or a single-org user's only org. It refuses to GUESS only when the user is
+// multi-org with nothing bound.
+assert.equal(projectlessMutationNeedsOrg({ explicitOrg: 'ee', orgCount: 5 }), false, 'explicit org → allow');
+assert.equal(projectlessMutationNeedsOrg({ boundOrgId: 'causeway', orgCount: 5 }), false, 'bound project → allow (a real root, not the cursor)');
+assert.equal(projectlessMutationNeedsOrg({ activeProjectId: 'p1', orgCount: 5 }), false, 'active project → allow');
+assert.equal(projectlessMutationNeedsOrg({ isRemote: true, orgCount: 5 }), false, 'remote session → allow (adopts its own connection org)');
+assert.equal(projectlessMutationNeedsOrg({ orgCount: 1 }), false, 'single org → allow');
+assert.equal(projectlessMutationNeedsOrg({ orgCount: 0 }), false, 'unknown membership → allow (never block a legit write)');
+assert.equal(projectlessMutationNeedsOrg({ orgCount: 3 }), true, 'multi-org, nothing bound → BLOCK (refuse to guess)');
+
+// The xcode-build incident state: multi-org + a bound project sticky from an
+// earlier, unrelated project(open). Under Reading A a fork is NOT hard-blocked —
+// it lands in the active project's org (a real root) and the response RECEIPT names
+// that org, so the fork is visible instead of silent. Create and fork agree here by
+// design (one rule); the fix for the surprise is the receipt, not a block.
+const incident = { orgCount: 3, boundOrgId: 'causeway', activeProjectId: 'p1' };
+assert.equal(projectlessMutationNeedsOrg(incident), false, 'incident state: fork allowed into the bound org — awareness comes from the receipt (Reading A)');
+
+// The genuinely ambiguous case still errors for a fork, exactly as for a create:
+assert.equal(projectlessMutationNeedsOrg({ orgCount: 3 }), true, 'multi-org fork with nothing bound → BLOCK before any copy is created');
+
+console.log('org-guard policy OK');
+// Importing server.mjs builds the stdio MCP singleton, which opens a WS reconnect
+// loop that keeps the event loop alive. Assertions are done — exit deterministically.
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.14.5",
+  "version": "1.14.6",
   "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",
   "files": [