drafted 1.14.1 → 1.14.2

package/mcp/server.mjs

@@ -225,6 +225,9 @@ const TOOL_ANNOTATIONS = {
   // Identity — read-only introspection of THIS agent's session
   whoami:              { title: 'Session identity',    readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'Return THIS agent session\'s identity: its server-assigned human-readable name (the correlation key between an agent window and its web-app session tab), sessionId, userId, orgId, active projectId, editor label, server URL, and surfaced/alive state. Read-only. Use this — not guesses from the host environment — to report which session you are.' },
 
+  // Health — call once per session, right after whoami and before any real work
+  health:              { title: 'Server health',       readOnlyHint: true,  destructiveHint: false, openWorldHint: true,  description: 'Server reachability + installed MCP version/update status. Call this once per session, right after whoami and before doing any real work, so a required update surfaces before you act on stale tool behavior.' },
+
   // Projects
   project:             { title: 'Projects',            readOnlyHint: false, destructiveHint: false, openWorldHint: false, widgetUri: 'ui://widget/drafted-canvas-overview.html', description: 'Manage projects: list (start here), open (bind this agent session to a project — org derives from it), create (org= names where it is born), update, move to another org.' },
   get_org:             { title: 'Organization',        readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'List your orgs, the default org, and Google Drive availability (action="get", default), or fetch installed MCP update instructions (action="update_mcp"). There is no org switching — org derives from the resource you address; creates/searches take org=. When googleDrive.connected is true, strongly prefer Google Workspace frames for documents, sheets, and slides.' },
@@ -371,6 +374,10 @@ function tool(name, descOrSchema, schemaOrHandler, handler) {
     state.currentTool = name;
     trackUmamiEvent(UMAMI_EVENTS.MCP_TOOL_CALLED, { tool: name, projectId: state.projectId || undefined, source: 'mcp' });
     reportInstallationEvent(UMAMI_EVENTS.DRAFTED_MCP_REQUEST, { tool: name });
+    if (!hasAnnouncedSubstantiveWork && !NON_SUBSTANTIVE_TOOLS.has(name)) {
+      hasAnnouncedSubstantiveWork = true;
+      announceSubstantiveWork().catch(() => {});
+    }
     try {
       const requiredUpdateError = await getRequiredMcpUpdateError(name, args?.[0] || {});
       if (requiredUpdateError) return err(new Error(requiredUpdateError));
@@ -1140,15 +1147,27 @@ function getCurrentProjectContext() {
   return s.projectMeta || { id: s.projectId, slug: null, name: null, orgId: null };
 }
 
+function scheduleAgentWsRetry() {
+  clearTimeout(agentWsReconnectTimer);
+  agentWsReconnectTimer = setTimeout(() => {
+    connectAgentWs().catch((e) => {
+      console.error('[MCP-WS] Reconnect failed:', e?.message || e);
+    });
+  }, 5000);
+}
+
 async function connectAgentWs() {
   await ensureSession();
   const auth = getAuthHeaders();
-  if (!auth.Cookie) return;
+  // No session yet (e.g. desktop sign-in still in progress) — retry instead of stranding
+  // the handshake forever, since there's no WebSocket here yet to trigger the close-based
+  // reconnect below.
+  if (!auth.Cookie) { scheduleAgentWsRetry(); return; }
 
   const serverUrl = getServerUrl().replace(/^http/, 'ws');
   try {
     agentWs = new WebSocket(serverUrl, { headers: auth });
-  } catch { return; }
+  } catch { scheduleAgentWsRetry(); return; }
 
   agentWs.on('open', () => {
     console.error('[MCP-WS] Connected');
@@ -1182,12 +1201,7 @@ async function connectAgentWs() {
     // and survive server restarts, so reusing the clone keeps this agent's surface (and
     // its playful tab name) stable across blips — otherwise every reconnect re-clones a
     // fresh session → a NEW greyed tab with a NEW name. A real 401 still triggers re-clone.
-    clearTimeout(agentWsReconnectTimer);
-    agentWsReconnectTimer = setTimeout(() => {
-      connectAgentWs().catch((e) => {
-        console.error('[MCP-WS] Reconnect failed:', e?.message || e);
-      });
-    }, 5000);
+    scheduleAgentWsRetry();
   });
 
   agentWs.on('error', () => {
@@ -1223,6 +1237,28 @@ async function joinAgentWsRoom(projectId) {
   }
 }
 
+// Tools that are pure introspection/sign-in, not "the agent started working" — excluded from
+// the first-substantive-action ping below so a bare whoami/health/auth never yanks the
+// desktop app's window to the front.
+const NON_SUBSTANTIVE_TOOLS = new Set(['whoami', 'health', 'auth']);
+let hasAnnouncedSubstantiveWork = false;
+
+// Tell the server this agent has started real work (first call past whoami/health/auth this
+// process), so it can foreground the desktop app's window. Fire-and-forget — never blocks or
+// fails the tool call that triggered it.
+async function announceSubstantiveWork() {
+  if (!agentWs || agentWs.readyState > WebSocket.OPEN) {
+    await connectAgentWs();
+  }
+  if (!agentWs) return;
+  const msg = JSON.stringify({ type: 'agent-active', projectId: getState().projectId || null });
+  if (agentWs.readyState === WebSocket.OPEN) {
+    agentWs.send(msg);
+  } else if (agentWs.readyState === WebSocket.CONNECTING) {
+    agentWs.once('open', () => agentWs.send(msg));
+  }
+}
+
 // Clone session and connect WebSocket on startup (delayed to let server be ready).
 // Guarded because createMcpServer() runs per HTTP request — the bootstrap must
 // fire exactly once per process, not per request.
@@ -1684,11 +1720,35 @@ async function sessionSurfaceBlock() {
 // Identity: report THIS agent session's own surface identity. Read-only — no state changed.
 tool('whoami', 'Return THIS agent session\'s identity: its server-assigned human-readable name (the correlation key between an agent window and its web-app session tab), sessionId, userId, orgId, active projectId, editor label, server URL, and surfaced/alive state. Read-only.', {}, async () => {
   try {
+    const block = await sessionSurfaceBlock();
+    // Tell the agent to actually surface its name to the user — returning `name` in the JSON isn't
+    // enough; without an explicit instruction agents rarely say which session they are, so users
+    // can't match them to their tab on the Drafted surface.
+    const instruction = block.name
+      ? `You are the session named "${block.name}". Tell the user you're "${block.name}" in your reply so they can match you to your tab on the Drafted surface.`
+      : undefined;
     return ok({
       server: getServerUrl(),
       editor: (process.env.DRAFTED_AGENT_NAME || '').trim() || null,
       agentLabel: getAgentLabel(),
-      ...(await sessionSurfaceBlock()),
+      ...block,
+      ...(instruction ? { instruction } : {}),
+    });
+  } catch (error) { return err(error); }
+});
+
+// Health: server reachability + installed-MCP staleness, meant to be the second call of a
+// session (right after whoami, before real work) so a required update surfaces early instead
+// of depending on an agent remembering to call get_org. Cached per-process — `whoami` stays
+// network-free between health checks, and repeat `health` calls in one session are free too.
+tool('health', {}, async () => {
+  try {
+    const mcpUpdate = await getCachedMcpUpdateMetadata();
+    return ok({
+      server: getServerUrl(),
+      ok: mcpUpdate.status !== 'unknown',
+      mcpVersion: PACKAGE_VERSION,
+      mcpUpdate,
     });
   } catch (error) { return err(error); }
 });
@@ -1705,7 +1765,6 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
   folder: z.string().nullable().optional().describe('[update] folder name (null to remove from folder)'),
   layers: z.array(z.object({}).passthrough()).optional().describe('[update] full layers array replacement. Use ls / to read current layers first.'),
   targetOrgId: z.string().optional().describe('[move] destination organization ID. Get org IDs from action=list (each project has an orgId field) or get_org. Both source and target org must include the current user.'),
-  skipBrowser: z.boolean().optional().describe('[open] skip opening/navigating a browser tab (use when the user already has the project open, e.g. from an invite snippet)'),
   format: z.string().optional().describe('[export] "files" returns {files:[{path,content}]} paginated via limit/offset (compact=true for paths only) instead of writing a local dir (stdio) or returning a download URL (remote).'),
   limit: z.number().optional().describe('[export] max files per page for format="files" (default 100, max 500)'),
   offset: z.number().optional().describe('[export] pagination offset for format="files"'),
@@ -1750,7 +1809,7 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
         return ok(data, { structuredContent });
       }
       case 'open': {
-        const { projectId, skipBrowser } = args;
+        const { projectId } = args;
         if (!projectId) throw new Error('projectId required for action=open');
         const result = await api('POST', '/api/project/switch', { projectId });
         joinAgentWsRoom(projectId);
@@ -1767,18 +1826,17 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
         } catch { /* fall back to projectId */ }
         setMcpActiveProject(projectId, projectMeta);
         const url = `${base}/project/${projectSlug}`;
+        // Surfacing to the user is the focus mechanism's job now (agent-active ping ->
+        // desktop window / notification+glow for browser tabs) — this used to also force
+        // `exec('open <url>')` on the MCP host machine, an unsolicited GUI action that both
+        // duplicated the focus mechanism and did nothing useful for remote/hosted MCP mode
+        // (no GUI to open on Drafted's own server). `url` is still returned below for the
+        // agent/human to open manually.
         let navigated = 0;
-        if (!skipBrowser) {
-          try {
-            const nav = await api('POST', '/api/project/navigate', { projectId });
-            navigated = nav.navigated || 0;
-          } catch { /* server may not support navigate yet */ }
-          if (navigated === 0) {
-            const { exec } = await import('child_process');
-            const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-            exec(`${cmd} ${JSON.stringify(url)}`);
-          }
-        }
+        try {
+          const nav = await api('POST', '/api/project/navigate', { projectId });
+          navigated = nav.navigated || 0;
+        } catch { /* server may not support navigate yet */ }
         // G4/G5 auto-inject (locked design): the project's attached skills + anchors
         // are pushed into the open response within the per-project context budget,
         // replacing the reject-style gate. Prefer the server-computed `priming`
@@ -2318,12 +2376,23 @@ async function getMcpUpdateMetadata() {
       mode,
       distribution: mode === 'stdio' ? 'npm-stdio' : 'hosted-http',
       update: { command: null, helper: null, packageManager: 'npm' },
-      restart: { required: false, guidance: 'Drafted MCP update status is unavailable; get_org still succeeded.' },
+      restart: { required: false, guidance: 'Drafted MCP update status is unavailable; this call still succeeded.' },
       checkedAt: null,
     };
   }
 }
 
+// Process-lifetime cache: `health` is meant to be called every session, so avoid a network
+// round-trip on repeat calls. `get_org` shares the cache too (same underlying data).
+let mcpUpdateCache = null; // { data, fetchedAt }
+const MCP_UPDATE_CACHE_MS = 5 * 60_000;
+async function getCachedMcpUpdateMetadata() {
+  if (mcpUpdateCache && (Date.now() - mcpUpdateCache.fetchedAt) < MCP_UPDATE_CACHE_MS) return mcpUpdateCache.data;
+  const data = await getMcpUpdateMetadata();
+  mcpUpdateCache = { data, fetchedAt: Date.now() };
+  return data;
+}
+
 
 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.'),
@@ -2347,7 +2416,7 @@ tool('get_org', {
     const activeOrg = sessionOrgId ? (orgs.find(o => o.id === sessionOrgId) || null) : null;
 
     const googleDrive = await getGoogleDriveAvailability();
-    const mcpUpdate = await getMcpUpdateMetadata();
+    const mcpUpdate = await getCachedMcpUpdateMetadata();
 
     let members = [];
     if (sessionOrgId) {

package/package.json

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