drafted 1.14.1 → 1.14.3

package/cli/drafted.mjs

@@ -579,10 +579,22 @@ program
 
     // Start server in background
     const serverPath = join(__dirname, '../server/server.mjs');
-    const { openSync } = await import('fs');
-    const outLog = openSync(join(DEFAULT_STATE_DIR, 'server.log'), 'w');
     const tsxPath = join(__dirname, '../node_modules/.bin/tsx');
     const instrumentPath = join(__dirname, '../server/instrument.mjs');
+    // A global `npm install -g drafted` only ships the CLI/MCP client (see
+    // package.json "files") — the Express server and its src/db, src/auth,
+    // src/middleware sources, plus the tsx devDependency needed to run them,
+    // are not part of that install. This only works from a full git checkout.
+    if (!existsSync(tsxPath) || !existsSync(serverPath)) {
+      console.error('Error: cannot start the server from this installation.');
+      console.error('This looks like a global `npm install -g drafted` install, which ships only the CLI/MCP client, not the full server.');
+      console.error('To bring the local server back up, either:');
+      console.error('  - reopen the Drafted desktop app, or');
+      console.error('  - run from a full source checkout: git clone the drafted repo, then `npm install && npm run dev`');
+      process.exit(1);
+    }
+    const { openSync } = await import('fs');
+    const outLog = openSync(join(DEFAULT_STATE_DIR, 'server.log'), 'w');
     const child = spawn(tsxPath, ['--import', instrumentPath, serverPath], {
       detached: true,
       stdio: ['ignore', outLog, outLog],
@@ -647,11 +659,10 @@ program
       console.log('✅ Drafted server is running');
       console.log(`   PID: ${pid}`);
       console.log(`   URL: http://localhost:${port}`);
-      console.log(`   Frames: ${state.frames.length}`);
 
       // Try to ping server
       try {
-        const response = await authFetch(`http://localhost:${state.port}/status`);
+        const response = await authFetch(`http://localhost:${port}/status`);
         const data = await response.json();
         console.log(`   Status: ${data.status}`);
       } catch (error) {

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.
@@ -1536,7 +1572,17 @@ if (!isRemote) tool('auth', 'Sign in to Drafted. On a local install the DESKTOP
         const sid = await waitForBootstrapAuth(Date.now() + 180000);
         if (!sid) throw new Error('Timed out waiting for sign-in. Complete sign-in in the Drafted app window, then retry.');
         getState().sessionId = null;
-        await cloneSession();
+        // cloneSession() can fail transiently right after the app plants the bootstrap
+        // session (e.g. the server hasn't finished committing it yet) — retry briefly
+        // before giving up, and never report logged_in unless a session actually landed.
+        let cloned = await cloneSession();
+        for (let attempt = 0; !cloned && attempt < 3; attempt++) {
+          await new Promise((r) => setTimeout(r, 750));
+          cloned = await cloneSession();
+        }
+        if (!cloned || !getState().sessionId) {
+          throw new Error('Signed in, but could not establish a session yet. Retry your request in a moment.');
+        }
         connectAgentWs();
         return ok({ status: 'logged_in', via: 'desktop-app' });
       }
@@ -1684,11 +1730,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 +1775,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 +1819,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 +1836,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 +2386,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 +2426,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.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",
   "files": [

package/src/shared/minion-presets.mjs

@@ -0,0 +1,67 @@
+// Deploy-seeded starting points for the Minion builder ("presets"). Pure data,
+// shared for every org (no per-org copy). Each preset pre-wires the builder
+// config for a use case; the user then edits any field. `config: null` means
+// the full blank/advanced form. See feature card: contexts/minions/feature-card.
+//
+// A preset's `config` is a partial minion the builder hydrates via showConfig:
+//   { description, checklist:[{label,evidence,required}], output:{mode,grouping,format,register} }
+// Drive-only bits (format:google-*, register) degrade to a markdown record when
+// the org has no Google Drive connected — the builder simply hides those fields.
+export const MINION_PRESETS = [
+  {
+    key: 'reports-sheet',
+    name: 'Collect reports → spreadsheet',
+    icon: '▤',
+    tagline: 'A form people fill out. Each one becomes a document + a new row in a master sheet.',
+    config: {
+      description: '',
+      checklist: [
+        { label: 'Department', evidence: 'text', required: true },
+        { label: 'What happened', evidence: 'text', required: true },
+        { label: 'Attachment (file or photo)', evidence: 'file', required: false },
+      ],
+      output: {
+        mode: 'generate',
+        grouping: 'frame',
+        format: 'google-doc',
+        register: { columns: ['Date', 'Department', 'Summary', 'Report link'] },
+      },
+    },
+  },
+  {
+    key: 'files',
+    name: 'Gather files / evidence',
+    icon: '▦',
+    tagline: 'Collect photos & documents into one organized folder, with a short summary.',
+    config: {
+      description: '',
+      checklist: [
+        { label: 'Files or photos', evidence: 'file', required: true },
+        { label: 'A short note about them', evidence: 'text', required: false },
+      ],
+      output: { mode: 'generate', grouping: 'lane' },
+    },
+  },
+  {
+    key: 'survey',
+    name: 'Survey / intake form',
+    icon: '≡',
+    tagline: 'Ask a set of questions. One tidy record per response.',
+    config: {
+      description: '',
+      checklist: [
+        { label: 'Question 1', evidence: 'text', required: true },
+        { label: 'Question 2', evidence: 'text', required: true },
+        { label: 'Question 3', evidence: 'text', required: false },
+      ],
+      output: { mode: 'generate', grouping: 'frame' },
+    },
+  },
+  {
+    key: 'blank',
+    name: 'Blank (advanced)',
+    icon: '+',
+    tagline: 'Start from raw settings — full control.',
+    config: null,
+  },
+];