drafted 1.19.7 → 1.19.9

package/README.md

@@ -18,10 +18,17 @@ Drafted is a native producer and consumer of the **Open Knowledge Format (OKF) v
 **Claude Code, Codex, or any MCP client** — installs the MCP server, the Drafted skill, *and* the eight slash commands (into `~/.claude/commands/drafted/` and `~/.codex/prompts/drafted/`):
 
 ```bash
-curl -fsSL https://drafted.live/install.sh | bash        # macOS / Linux
-irm https://drafted.live/install.ps1 | iex               # Windows
+# macOS / Linux — download, then run the local file:
+curl -fsSL https://drafted.live/install.sh -o /tmp/install-drafted.sh
+bash /tmp/install-drafted.sh
+
+# Windows (PowerShell) — download, then run the local file:
+Invoke-WebRequest https://drafted.live/install.ps1 -OutFile $env:TEMP\drafted-install.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File $env:TEMP\drafted-install.ps1
 ```
 
+> **Why not `curl | bash` / `irm | iex`?** Heuristic antivirus (Norton IDP, SmartScreen) flags the pipe-to-shell pattern as download-and-execute malware. Downloading the installer to a local file and running it avoids the false-positive block.
+
 > Adding the MCP server on its own (e.g. `claude mcp add`) gives you the tools without the skill or the commands.
 
 **Claude on the web (claude.ai) and Cowork** — install the plugin, not the bare connector. The plugin bundles the Drafted connector *plus* the Drafted skill and the eight slash commands (`/drafted:onboard-drafted`, `/drafted:create-project`, `/drafted:create-skill`, `/drafted:ingest`, `/drafted:extract`, `/drafted:improve-wiki`, `/drafted:improve-skill`, `/drafted:improve-project-harness`); adding the connector URL on its own gives you the tools with none of the guidance.

package/cli/drafted.mjs

@@ -10,6 +10,7 @@
 import { program } from 'commander';
 import { spawn, execSync, execFileSync } from 'child_process';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, unlinkSync, chmodSync } from 'fs';
+import { writeFile } from 'fs/promises';
 import { join, dirname, basename, resolve } from 'path';
 import { homedir, tmpdir, platform } from 'os';
 import { fileURLToPath } from 'url';
@@ -176,11 +177,18 @@ function getServerUrl() {
 function buildUpdateCommand() {
   const server = getServerUrl().replace(/\/$/, '');
   if (platform() === 'win32') {
-    const script = `$tmp = Join-Path $env:TEMP "drafted-install.ps1"; Invoke-WebRequest -UseBasicParsing "${server}/install.ps1" -OutFile $tmp; powershell -NoProfile -ExecutionPolicy Bypass -File $tmp`;
+    // Download the installer with Node, then spawn powershell -File on the LOCAL
+    // copy. Never `powershell -Command "Invoke-WebRequest ...; powershell -File
+    // ..."` — a fetch-and-execute trampoline on the command line is exactly what
+    // heuristic AV (Norton IDP.HEUR) flags as malware.
+    const tmp = path.join(os.tmpdir(), 'drafted-install.ps1');
+    const src = `${server}/install.ps1`;
     return {
       shell: 'powershell.exe',
-      args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', script],
-      manualCommand: script,
+      args: ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', tmp],
+      manualCommand: `Invoke-WebRequest -UseBasicParsing "${src}" -OutFile "${tmp}"
+powershell -NoProfile -ExecutionPolicy Bypass -File "${tmp}"`,
+      fetch: { url: src, dest: tmp },
     };
   }
   const script = `tmp=$(mktemp); curl -fsSL ${server}/install.sh -o "$tmp" && bash "$tmp"`;
@@ -505,7 +513,7 @@ program
   .description('Update the npm-installed Drafted MCP daemon')
   .option('--dry-run', 'Print update instructions without starting the updater')
   .option('--yes', 'Start the updater out-of-process')
-  .action((options) => {
+  .action(async (options) => {
     const update = buildUpdateCommand();
     const data = {
       started: false,
@@ -517,6 +525,20 @@ program
     };
 
     if (options.yes && !options.dryRun) {
+      if (update.fetch) {
+        const { url, dest } = update.fetch;
+        try {
+          const resp = await fetch(url);
+          if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+          await writeFile(dest, Buffer.from(await resp.arrayBuffer()));
+        } catch (err) {
+          console.error(`Could not download the installer: ${err.message}. Run the manual command below instead.`);
+          jsonOut(true, 'update', { ...data, started: false, error: String(err.message || err) });
+          console.log('No automatic update was started. Run the manual updater command:');
+          console.log(`  ${update.manualCommand}`);
+          process.exit(1);
+        }
+      }
       const child = spawn(update.shell, update.args, {
         detached: true,
         stdio: 'ignore',

package/install-mcp.sh

@@ -5,8 +5,9 @@ set -e
 # This script installs the Drafted MCP server and CLI globally via npm,
 # then registers it with Claude Desktop, Claude Code, Codex, and Cursor.
 #
-# Run with:
-#   curl -fsSL https://drafted.live/install.sh | bash
+# Run with (download first, then run the local file):
+#   curl -fsSL https://drafted.live/install.sh -o ~/Downloads/install-drafted.sh
+#   bash ~/Downloads/install-drafted.sh
 
 SERVER="https://drafted.live"
 INSTALLER_VERSION="1"
@@ -1254,7 +1255,7 @@ echo -e "${GREEN}${BOLD}You're all set!${RESET}"
 echo ""
 echo -e "  ${DIM}MCP name:${RESET}  ${BOLD}$INSTALL_NAME${RESET}"
 echo -e "  ${DIM}Server:${RESET}    ${BOLD}$INSTALL_SERVER${RESET}"
-echo -e "  ${DIM}To update production:${RESET}  rerun curl -fsSL https://drafted.live/install.sh | bash"
+echo -e "  ${DIM}To update production:${RESET}  rerun the installer from drafted.live/install (curl -fsSL https://drafted.live/install.sh -o /tmp/install-drafted.sh && bash /tmp/install-drafted.sh)"
 echo -e "  ${DIM}To uninstall:${RESET}  npm uninstall -g drafted --prefix ~/.drafted/npm-global && rm -rf ~/.drafted"
 echo ""
 echo -e "${YELLOW}${BOLD}"

package/mcp/server.mjs

@@ -384,11 +384,11 @@ const TOOL_ANNOTATIONS = {
   auth:                { title: 'Sign in',             readOnlyHint: false, destructiveHint: false, openWorldHint: true,  description: 'Sign in to Drafted. `action=get_link` returns a URL immediately and starts background approval polling; after the user opens the link, later Drafted tool calls also auto-consume the approved login. `action=login` opens a browser when needed and explicitly waits/polls for approval.' },
 
   // 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 — PLUS server health, the installed MCP version/update status (cached ~5min), and `googleDrive` — whether the working org has Google Drive connected: when `googleDrive.connected` is true, strongly prefer Google Workspace frames (.google-doc/.google-sheet/.google-slide) for docs, sheets, and decks; when false they cannot be created at all. Call once per session, right after starting, so a required update surfaces before you act on stale tool behavior. Read-only. Use this — not guesses from the host environment — to report which session you are.' },
+  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 (`authState` says whether this session is signed in, and `authNote` names the exact call that fixes it when it is not — never diagnose a null userId yourself) — PLUS server health, the installed MCP version/update status (cached ~5min), and `googleDrive` — whether the working org has Google Drive connected: when `googleDrive.connected` is true, strongly prefer Google Workspace frames (.google-doc/.google-sheet/.google-slide) for docs, sheets, and decks; when false they cannot be created at all. Call once per session, right after starting, so a required update surfaces before you act on stale tool behavior. Read-only. Use this — not guesses from the host environment — to report which session you are.' },
 
   // Session naming — the name-before-work gate: every agent session must set a short
   // name describing the work before any other tool call succeeds.
-  session:             { title: 'Session',              readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Name THIS agent session (and rename it later). The name is what the user sees on your surface tab — pick a short 2-3 word description of the work (e.g. "beoflow backend", "drafted fs work"). The name persists across reconnects and restarts; you only set it once unless the work changes. Dispatch by `action`: `name` (set/rename with the `name` param).' },
+  session:             { title: 'Session',              readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Name THIS agent session (and rename it later). The name is what the user sees on your surface tab — pick a short 2-3 word description of the work (e.g. "beoflow backend", "drafted fs work"). The name persists across reconnects and restarts; you only set it once unless the work changes. Dispatch by `action`: `name` (set/rename with the `name` param) or `update` (update the npm-installed Drafted MCP on THIS machine when whoami reports mcpUpdate.stale — run it yourself rather than handing the user a shell command; `dryRun` reports without starting it).' },
 
   // Comments — the review loop agents could previously only reach over raw HTTP
   comment:             { title: 'Comments',              readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Read and write review comments on frames. Comments are notes ABOUT THE WORK: they attach to a frame, optionally to one element inside it, and anyone who can see the frame sees them. Dispatch by `action`: list (paginated, compact mode), add (with an optional element anchor or a reply), resolve, reopen, delete. Use this to leave findings a human can action in place, and to read the feedback they left you.' },
@@ -2204,6 +2204,8 @@ async function sessionSurfaceBlock() {
   if (agentSurface) {
     return {
       sessionId,
+      authenticated: !!agentSurface.userId,
+      authState: agentSurface.userId ? 'authenticated' : 'signed_out',
       userId: agentSurface.userId ?? null,
       orgId: agentSurface.orgId ?? null,
       projectId: agentSurface.projectId ?? null,
@@ -2232,6 +2234,7 @@ async function sessionSurfaceBlock() {
     try {
       const res = await serverFetch(`${getServerUrl()}/auth/me`, { headers: { Cookie: `gc_session=${cookieSid}` } });
       if (res.ok) me = await res.json();
+      // else: the server ANSWERED and rejected this session — a real sign-out, not a blip.
     } catch (e) {
       // Transport failure, NOT a sign-out. Conflating the two made agents tell
       // users "you're signed out" during a network blip and start needless
@@ -2242,8 +2245,26 @@ async function sessionSurfaceBlock() {
     }
   }
   const nameRequired = !!me?.agentClone && !me?.surfaceName;
+  // A null userId used to come back BARE — no reason, no next step — and agents filled the
+  // gap by inventing one: a real report has an agent telling the user to look for a pending
+  // "device/session approval prompt" in the desktop app (no such prompt exists) and then
+  // waiting on it. Name which of the four states this is and the exact call that ends it.
+  const pending = (!me && !unreachable) ? getPendingDeviceCode() : null;
+  const authState = me?.userId ? 'authenticated'
+    : unreachable ? 'server_unreachable'
+    : pending ? 'awaiting_approval'
+    : cookieSid ? 'session_rejected'
+    : 'signed_out';
+  const AUTH_NOTES = {
+    awaiting_approval: `Sign-in started but NOT yet approved. Give the user this link and ask them to open it: ${pending?.verificationUrl || '(run auth(action="get_link") for a fresh link)'} — this session authenticates itself once they approve; nothing to approve inside the desktop app.`,
+    session_rejected: 'Not signed in: this machine has a stored Drafted session but the server rejected it (expired or revoked). Call auth(action="get_link") and give the user the returned URL. Do NOT ask them to look for an approval prompt in the desktop app — being signed in to the app does not sign THIS agent in.',
+    signed_out: 'Not signed in: no Drafted session on this machine. Call auth(action="get_link") and give the user the returned URL. Do NOT ask them to look for an approval prompt in the desktop app — being signed in to the app does not sign THIS agent in.',
+  };
   return {
     sessionId: cookieSid,
+    authenticated: !!me?.userId,
+    authState,
+    ...(AUTH_NOTES[authState] ? { authNote: AUTH_NOTES[authState] } : {}),
     userId: me?.userId ?? null,
     orgId: me?.currentOrg?.id ?? null,
     projectId: getState().projectId ?? null,
@@ -2254,6 +2275,9 @@ async function sessionSurfaceBlock() {
     color: null,
     surfaced: false,
     alive: false,
+    // `alive` is bare here where it isn't in the acked branch, and a bare false reads as
+    // "something is broken" — it only means the surface WebSocket hasn't acked yet.
+    aliveMeaning: 'The surface WebSocket has not acked this session yet, so no canvas is known to be open. Frame, wiki, and skill writes all persist normally — only focus/presence have nothing to draw on. Do not change what you write because of this, and do not report it as an error.',
     ...(unreachable ? {
       serverUnreachable: true,
       note: unreachableWhy || `Could not reach ${getServerUrl()} — identity UNKNOWN, not signed out. This is a network/transport failure: do not tell the user they are logged out and do not start a new login; retry when connectivity is back.`,
@@ -2285,7 +2309,7 @@ async function getGoogleDriveAvailability() {
 // reachability, and installed-MCP staleness in ONE bootstrap call. The update data is
 // cached (5min), so repeat `whoami` calls are free; the server-side update gate still
 // blocks mutating calls on its own, independent of this tool. 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 — PLUS server health, the installed MCP version/update status (cached ~5min), and `googleDrive` — whether the working org has Google Drive connected: when `googleDrive.connected` is true, strongly prefer Google Workspace frames (.google-doc/.google-sheet/.google-slide) for docs, sheets, and decks; when false they cannot be created at all. Call once per session, right after starting, so a required update surfaces before you act on stale tool behavior. Read-only.', {}, async () => {
+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 (`authState` says whether this session is signed in, and `authNote` names the exact call that fixes it when it is not — never diagnose a null userId yourself) — PLUS server health, the installed MCP version/update status (cached ~5min), and `googleDrive` — whether the working org has Google Drive connected: when `googleDrive.connected` is true, strongly prefer Google Workspace frames (.google-doc/.google-sheet/.google-slide) for docs, sheets, and decks; when false they cannot be created at all. Call once per session, right after starting, so a required update surfaces before you act on stale tool behavior. Read-only.', {}, async () => {
   try {
     // Ensure the child clone exists BEFORE reading identity — otherwise the /auth/me
     // fallback (pre-WS-ack) queries the ROOT session and reports the wrong naming state.
@@ -2295,7 +2319,19 @@ tool('whoami', 'Return THIS agent session\'s identity: its server-assigned human
     // 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.nameRequired
+    // Auth outranks naming: an unauthenticated session has nothing to name, and leaving the
+    // instruction empty is what let agents invent their own explanation for the null ids.
+    // A stale install can now fix ITSELF — say so here, since this is where staleness is
+    // reported and an agent that only reads `stale: true` goes back to the user with a shell
+    // command they didn't ask for.
+    const staleNote = mcpUpdate.stale && mcpUpdate.mode === 'stdio'
+      ? ` This machine's installed Drafted MCP is out of date (${mcpUpdate.currentVersion} → ${mcpUpdate.latestVersion || 'latest'})${mcpUpdate.required ? ' and BELOW the minimum required version, so mutating tools are blocked' : ''}. Call session(action="update") to update it yourself — do not hand the user a shell command.`
+      : '';
+    const instruction = block.authNote
+      ? block.authNote + staleNote
+      : staleNote && !block.nameRequired
+      ? (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.` : '') + staleNote
+      : block.nameRequired
       ? `You have NO session name yet — the name-before-work gate blocks all other tools until you set one. Name this session by the work you're doing with the user: a short 2-3 word description (suggested: "${block.suggestedName || '...'}"). Set it now with session(action="name", name="<your name>"), then tell the user you're "<name>".`
       : 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.`
@@ -2314,13 +2350,69 @@ tool('whoami', 'Return THIS agent session\'s identity: its server-assigned human
   } catch (error) { return err(error); }
 });
 
+// Self-update: run the installed CLI's own updater so THIS machine's stale stdio MCP can be
+// refreshed from inside a tool call. Before this, the only path was telling the user to run a
+// shell command — which a web/Cowork agent cannot do at all, and which a stale install needs
+// most (an out-of-date MCP is exactly the session least able to ask for help). The updater
+// mechanics live in ONE place, `drafted update --yes` (cli/drafted.mjs) — do not reimplement
+// the installer command here, that's the two-writers drift.
+//
+// The `drafted` bin is resolved at the FIXED prefix first: the stdio MCP resolves from
+// ~/.drafted/npm-global, which a non-login shell's PATH does not carry, so bare `drafted`
+// finds nothing (or worse, a different install) on many machines.
+function installedDraftedBin() {
+  const prefixed = platform() === 'win32'
+    ? join(homedir(), '.drafted', 'npm-global', 'drafted.cmd')
+    : join(homedir(), '.drafted', 'npm-global', 'bin', 'drafted');
+  return existsSync(prefixed) ? prefixed : 'drafted';
+}
+
+async function updateInstalledMcp({ dryRun = false } = {}) {
+  try {
+    const metadata = await getMcpUpdateMetadata();
+    const instructions = buildInstalledMcpUpdateInstructions(metadata);
+    // Hosted HTTP MCP has no local daemon — instructions already say so.
+    if (!instructions.updateSupported) return ok({ ...instructions, action: 'update' });
+    if (dryRun) return ok({ ...instructions, action: 'update', started: false, dryRun: true });
+
+    const bin = installedDraftedBin();
+    const result = await new Promise((resolve) => {
+      execFile(bin, ['update', '--yes', '--json'], { timeout: 60_000 }, (error, stdout) => {
+        if (error) return resolve({ ok: false, error: error.code === 'ENOENT' ? `Drafted CLI not found (looked for ${bin})` : (error.killed ? 'Updater did not start within 60s' : error.message) });
+        try { resolve({ ok: true, data: JSON.parse(stdout) }); }
+        catch { resolve({ ok: true, data: null }); }
+      });
+    });
+
+    if (!result.ok) {
+      return ok({
+        ...instructions,
+        action: 'update',
+        started: false,
+        error: result.error,
+        note: `Could not start the updater from this process (${result.error}). Give the user this command to run in a terminal instead: ${instructions.manualCommand}`,
+      });
+    }
+    return ok({
+      ...instructions,
+      action: 'update',
+      started: true,
+      // Be exact about what did and did not happen: the installer runs DETACHED and does not
+      // replace the already-loaded process, so "updated" would be a lie until a restart.
+      note: 'The updater is running in the background (~30-60s). It does NOT replace this already-running MCP process: tell the user to restart their agent/editor once it finishes, then call whoami to confirm the new mcpVersion.',
+    });
+  } catch (error) { return err(error); }
+}
+
 // Session naming: set/rename THIS agent session's name — the name-before-work gate stays
 // closed until this succeeds. The name persists server-side (sessions.surface_name), so
 // reconnects and server restarts keep it and the gate never re-fires for a named session.
-tool('session', 'Name THIS agent session (and rename it later). The name is what the user sees on your surface tab — pick a short 2-3 word description of the work (e.g. "beoflow backend", "drafted fs work"). The name persists across reconnects and restarts; you only set it once unless the work changes.', {
-  action: z.enum(['name']).describe('Operation — currently only `name` (set/rename this session).'),
+tool('session', 'Manage THIS agent session. `action="name"` sets/renames it — the name is what the user sees on your surface tab, so pick a short 2-3 word description of the work (e.g. "beoflow backend"); it persists across reconnects and restarts. `action="update"` updates the npm-installed Drafted MCP on THIS machine when whoami reports mcpUpdate.stale — run it yourself instead of asking the user to run a shell command.', {
+  action: z.enum(['name', 'update']).describe('Operation: `name` (set/rename this session) or `update` (update the installed Drafted MCP on this machine).'),
   name: z.string().optional().describe('[name] the session name — a short 2-3 word description of the work (e.g. "beoflow backend"). Max 5 words / 50 chars.'),
-}, async ({ action, name }) => {
+  dryRun: z.boolean().optional().describe('[update] report what the update would do without starting it.'),
+}, async ({ action, name, dryRun }) => {
+  if (action === 'update') return updateInstalledMcp({ dryRun });
   if (action !== 'name') return err(new Error(`unknown session action: ${action}`));
   if (!name || !String(name).trim()) return err(new Error('name required — a short 2-3 word description of the work, e.g. session(action="name", name="beoflow backend")'));
   try {
@@ -3716,7 +3808,7 @@ function buildInstalledMcpUpdateInstructions(updateMetadata = null) {
 
   const server = getServerUrl().replace(/\/$/, '');
   const manualCommand = platform() === 'win32'
-    ? `$tmp = Join-Path $env:TEMP "drafted-install.ps1"; Invoke-WebRequest -UseBasicParsing "${server}/install.ps1" -OutFile $tmp; powershell -NoProfile -ExecutionPolicy Bypass -File $tmp`
+    ? `Invoke-WebRequest -UseBasicParsing "${server}/install.ps1" -OutFile "$env:TEMP\drafted-install.ps1"\npowershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\drafted-install.ps1"`
     : `tmp=$(mktemp); curl -fsSL ${server}/install.sh -o "$tmp" && bash "$tmp"`;
 
   return {

package/package.json

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