drafted 1.11.38 → 1.12.1

package/mcp/server.mjs

@@ -197,6 +197,10 @@ CONTEXT RULES (follow these before every action):
   - WIKI CHECK: Before acting on any request, search the org wiki for relevant conventions, existing designs, and prior decisions. Use wiki(action="search") with relevant keywords.
   - LAYER CONTEXT: Before reading or mutating a frame, read all anchored frames in the same layer. Anchored frames are per-layer required reading (style guides, design systems, conventions). The server enforces this mechanically for writes/edits/deletes/moves — but proactively reading anchored frames before any frame operation prevents wasted work.
 IMPORTANT: Any URL containing /f/{uuid} is a Drafted frame link — ALWAYS use read(path=URL) to get frame content, focus(target=URL) to pan the canvas to it. Never curl or WebFetch Drafted URLs.`,
+}, {
+  // Initialize instructions: the agent-identity contract, so an agent learns its own
+  // tab name + the right way to read it WITHOUT having to "think to" call a tool.
+  instructions: `SESSION IDENTITY — read this first: you run as a NAMED session tab visible to the user on their Drafted surface. Your session has a human-readable name + emoji (e.g. "Sly Owl") — that name is how the user matches YOUR window to the tab they see, so identify yourself by it when it matters which agent you are. Read it from get_org (response field "session.name") or from the whoami tool; call whoami to refresh after a reconnect.`,
 });
 
 const layerKeys = Object.keys(LAYERS);
@@ -215,6 +219,9 @@ const TOOL_ANNOTATIONS = {
   // Auth — initiates external browser / email flows
   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 + emoji (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.' },
+
   // Projects
   project:             { title: 'Projects',            readOnlyHint: false, destructiveHint: false, openWorldHint: false, widgetUri: 'ui://widget/drafted-canvas-overview.html', description: 'Manage projects: list (start here), open (switch active project), create, update, move to another org.' },
   get_org:             { title: 'Organization',        readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Get the active organization (action="get", default), Google Drive availability, or switch to a different org (action="switch", orgId=...). Use switch when you need wiki/skill work in an org that has no projects — opening a project also switches, but is unavailable in empty orgs. When googleDrive.connected is true, strongly prefer Google Workspace frames for documents, sheets, and slides.' },
@@ -1064,6 +1071,10 @@ function withProjectBreadcrumb(result) {
 
 let agentWs = null;
 let agentWsReconnectTimer = null;
+// Cached agent-hello-ack: this agent's own surface identity (name/emoji/alive) as
+// assigned by the server. The playful name is the correlation key between an agent
+// window and its web-app session tab; whoami reads it from here.
+let agentSurface = null;
 
 function setMcpActiveProject(projectId, meta = null) {
   const s = getState();
@@ -1115,6 +1126,21 @@ async function connectAgentWs() {
     }
   });
 
+  agentWs.on('message', (raw) => {
+    // agent-hello-ack carries this agent's server-assigned surface identity back on the
+    // owning connection. Cache it so whoami can report the name without a prod WS probe.
+    try {
+      const m = JSON.parse(raw.toString());
+      if (m.type === 'agent-hello-ack') {
+        agentSurface = {
+          sessionId: m.sessionId, userId: m.userId, orgId: m.orgId, projectId: m.projectId,
+          name: m.name, emoji: m.emoji, alive: m.alive, surfaced: true,
+          capturedAt: Date.now(),
+        };
+      }
+    } catch { /* ignore non-JSON / unexpected */ }
+  });
+
   agentWs.on('close', () => {
     console.error('[MCP-WS] Disconnected, reconnecting in 5s...');
     agentWs = null;
@@ -1191,9 +1217,11 @@ async function getCurrentOrgId() {
   return ctx?.id || null;
 }
 
-// Returns { id, name } for the org bound to THIS MCP session. Each session is
-// independent on purpose — parallel agents can run on different orgs. Cache
-// is per-session, not module-global, so concurrent OAuth users can't collide.
+// Returns { id, name } for the org this MCP process is currently scoped to (the
+// session row's org_id, which the server resolves per-request via X-Drafted-Org).
+// Each MCP process is independent — parallel agents can run scoped to different
+// orgs. Cache is per-session-bucket, not module-global, so concurrent OAuth
+// users can't collide.
 async function getCurrentOrgContext() {
   const sess = getSessionState();
   if (sess.cachedOrgId && Date.now() - sess.cachedOrgIdTime < 30000) return sess.cachedOrgId;
@@ -1489,6 +1517,58 @@ if (!isRemote) tool('auth', 'Sign in to Drafted. `action=get_link` returns a ver
   } catch (error) { return err(error); }
 });
 
+// THIS-session surface identity: the playful name + emoji (correlation key between an
+// agent window and its web-app session tab), ids, and surfaced/alive state. Built from
+// the cached agent-hello-ack; falls back to /auth/me for userId/org before the first ack.
+// Shared by `whoami` AND surfaced in `get_org`'s response so an agent learns its name
+// from the tool it already calls — it must not have to "think to" ask.
+async function sessionSurfaceBlock() {
+  const sessionId = agentSurface?.sessionId || getState().sessionId || null;
+  if (agentSurface) {
+    return {
+      sessionId,
+      userId: agentSurface.userId ?? null,
+      orgId: agentSurface.orgId ?? null,
+      projectId: agentSurface.projectId ?? null,
+      name: agentSurface.name,
+      emoji: agentSurface.emoji,
+      surfaced: true,
+      alive: !!agentSurface.alive,
+    };
+  }
+  // No WS ack yet — best-effort identity from /auth/me so callers still get a userId/org.
+  const cookieSid = sessionId || getBootstrapSessionId();
+  let me = null;
+  if (cookieSid) {
+    try {
+      const res = await fetch(`${getServerUrl()}/auth/me`, { headers: { Cookie: `gc_session=${cookieSid}` } });
+      if (res.ok) me = await res.json();
+    } catch { /* not yet authenticated */ }
+  }
+  return {
+    sessionId: cookieSid,
+    userId: me?.userId ?? null,
+    orgId: me?.currentOrg?.id ?? null,
+    projectId: getState().projectId ?? null,
+    name: null,
+    emoji: null,
+    surfaced: false,
+    alive: false,
+  };
+}
+
+// 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 + emoji (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 {
+    return ok({
+      server: getServerUrl(),
+      editor: (process.env.DRAFTED_AGENT_NAME || '').trim() || null,
+      agentLabel: getAgentLabel(),
+      ...(await sessionSurfaceBlock()),
+    });
+  } catch (error) { return err(error); }
+});
+
 // ── Project management tools (direct HTTP) ────────────────────────
 
 tool('project', 'START HERE for project management. Dispatch by `action`: list (lists all projects across all orgs — always call first), open (switch the active project; required before reading/writing frames), create (new project, optionally from a template), update (change name/folder/description/layers), move (transfer to another org). Opening a project auto-switches the org. To change orgs WITHOUT a project (for wiki/skill work in an empty org), use get_org(action="switch", orgId=...). **Skill gate:** projects with attached skills will REJECT all mutations (write, edit, mv, rm, shape, group, connector, layout, layer, asset upload) until you have loaded each attached skill via skill(action="load"). Skills tell you HOW to do the work — they\'re not optional. Open returns the attached skill list and auto-inlines content for projects with ≤3 skills.', {
@@ -1497,7 +1577,7 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
   name: z.string().optional().describe('[create|update] project name'),
   description: z.string().nullable().optional().describe('[create|update] project description'),
   templateSlug: z.string().optional().describe('[create] template slug (e.g. "web-design", "mobile-app", "landing-page")'),
-  org: z.string().optional().describe('[create] org slug or id to create the project in, without switching the session. Defaults to the bound/active org.'),
+  org: z.string().optional().describe('[create] org slug or id to create the project in, without switching the active org. Defaults to the active org.'),
   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.'),
@@ -1626,7 +1706,7 @@ tool('project', 'START HERE for project management. Dispatch by `action`: list (
         const body = { name };
         if (description) body.description = description;
         if (templateSlug) body.templateSlug = templateSlug;
-        // `org` targets a specific org without switching the session cursor.
+        // `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)));
       }
@@ -2065,12 +2145,13 @@ tool('get_org', {
       const activeOrg = (orgs || []).map(o => ({ id: o.orgId || o.id, name: o.orgName || o.name })).find(o => o.id === me?.orgId) || null;
       const googleDrive = await getGoogleDriveAvailability();
       const mcpUpdate = await getMcpUpdateMetadata();
-      return ok({ switched: true, activeOrg, googleDrive, mcpVersion: PACKAGE_VERSION, mcpUpdate, note: 'Active org switched. Wiki and skill calls now target this org. Active project cleared — open a project (or stay org-scoped for wiki/skill). If googleDrive.connected is true, prefer Google Workspace frames for docs, sheets, and slides.' });
+      const session = await sessionSurfaceBlock();
+      return ok({ switched: true, activeOrg, googleDrive, mcpVersion: PACKAGE_VERSION, mcpUpdate, session, note: 'Active org switched. Wiki and skill calls now target this org. Active project cleared — open a project (or stay org-scoped for wiki/skill). If googleDrive.connected is true, prefer Google Workspace frames for docs, sheets, and slides.' });
     }
 
-    // Source of truth = THIS MCP session's bound org (what mutations will actually
-    // hit). Each session is independent on purpose — multiple agents can run in
-    // parallel against different orgs. /auth/me reads sessions.org_id directly.
+    // 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.
     const me = await api('GET', '/auth/me');
     const sessionOrgId = me?.orgId || null;
 
@@ -2095,7 +2176,8 @@ tool('get_org', {
       googleDrive,
       mcpVersion: PACKAGE_VERSION,
       mcpUpdate,
-      note: "activeOrg is the org bound to THIS MCP session — what mutations will actually target. To switch orgs without creating a project, call get_org(action=\"switch\", orgId=\"...\"). Browser tabs and other MCP sessions for the same user can be on different orgs. If googleDrive.connected is true, strongly prefer Google Workspace frames for docs, sheets, and slides.",
+      session: await sessionSurfaceBlock(),
+      note: "activeOrg is the org this MCP process scopes its requests to (carried per-request as X-Drafted-Org); mutations target it. `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. To scope to a different org without opening a project, call get_org(action=\"switch\", orgId=\"...\"). Concurrent MCP sessions and browser tabs for the same user can be scoped to different orgs. If googleDrive.connected is true, strongly prefer Google Workspace frames for docs, sheets, and slides.",
     });
   } catch (error) { return err(error); }
 });
@@ -3029,7 +3111,7 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
   path: z.string().optional().describe('[read_file|update_file] relative path inside skill directory (e.g. "examples/react.md")'),
   offset: z.number().optional().describe('[search|list] skip N results for pagination; [read_file] start reading at this byte offset (default 0) — for large files (e.g. a >90KB app-frame bundle) read in chunks using the returned nextOffset until truncated=false'),
   maxBytes: z.number().optional().describe('[read_file] return at most this many bytes from offset (default: whole remaining file). Response reports totalSize/offset/truncated/nextOffset.'),
-  org: z.string().optional().describe('[fork|push|update] resolve/fork into this Drafted org (id or name); scopes the request without switching the session'),
+  org: z.string().optional().describe('[fork|push|update] resolve/fork into this Drafted org (id or name); scopes the request without switching the active org'),
   setup: z.array(z.string()).optional().describe('[add|update] setup command(s) (in order) run on materialize to build a source-only skill, e.g. ["npm ci","npm run build"]'),
   files: z.array(z.object({ path: z.string(), content: z.string() })).optional().describe('[push] source files to push (path + UTF-8 content); server strips artifacts + enforces caps'),
   dir: z.string().optional().describe('[push] local directory to push instead of files[]; walked locally (heavy dirs, .skillinstall/, and .skillignore pre-filtered), server re-enforces. On push the dir\'s .gitignore is auto-updated to exclude .skillinstall/ (the rebuildable bundle).'),
@@ -3251,7 +3333,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
   action: z.enum(['ls', 'recent', 'read', 'search', 'links', 'log', 'health', 'write', 'edit', 'mv', 'rm', 'source-register', 'source-list', 'source-get', 'bulk-write']).describe('Operation to perform.'),
   path: z.string().optional().describe('[ls|read|links] wiki path. For ls: default / (root). For read: required. For links: required.'),
   pageId: z.string().optional().describe('[read|edit|mv|rm|links] page UUID (from read/search). UUID-first: addresses the page directly, org auto-derives — no org needed and no path lookup. Preferred over path for an existing page.'),
-  org: z.string().optional().describe('[write] org slug or id to create/target the page in, without switching the session. [search] scope the search to this org (default: search ALL your orgs). Required to create a page when you belong to more than one org and none is bound.'),
+  org: z.string().optional().describe('[write] org slug or id to create/target the page in, without switching the active org. [search] scope the search to this org (default: search ALL your orgs). Required to create a page when you belong to more than one org and none is active.'),
   recursive: z.boolean().optional().describe('[ls] list recursively with depth indicators'),
   limit: z.number().optional().describe('[recent|search] max results (recent default 10, search default 25)'),
   query: z.string().optional().describe('[search] term to search in title, path, and content'),
@@ -3507,7 +3589,7 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
         if (frontmatter !== undefined) body.frontmatter = frontmatter;
 
         // Check if page exists — if so, update; otherwise create. `orgHeader`
-        // (the `org` arg) targets a specific org without switching the session.
+        // (the `org` arg) targets a specific org without switching the active org.
         try {
           const existing = await api('GET', `/api/wiki/page?path=${encodeURIComponent(normalized)}`, undefined, orgHeader);
           const result = await api('PATCH', `/api/wiki/pages/${existing.id}`, body, orgHeader);

package/package.json

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