drafted 1.12.0 → 1.12.2

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 (a Greek term, e.g. "Nous") — 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);
@@ -216,7 +220,7 @@ 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 + 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.' },
+  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.' },
 
   // 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.' },
@@ -1067,7 +1071,7 @@ function withProjectBreadcrumb(result) {
 
 let agentWs = null;
 let agentWsReconnectTimer = null;
-// Cached agent-hello-ack: this agent's own surface identity (name/emoji/alive) as
+// Cached agent-hello-ack: this agent's own surface identity (name/capital/color/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;
@@ -1130,7 +1134,7 @@ async function connectAgentWs() {
       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,
+          name: m.name, capital: m.capital, color: m.color, alive: m.alive, surfaced: true,
           capturedAt: Date.now(),
         };
       }
@@ -1213,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;
@@ -1511,49 +1517,56 @@ if (!isRemote) tool('auth', 'Sign in to Drafted. `action=get_link` returns a ver
   } catch (error) { return err(error); }
 });
 
-// Identity: report THIS agent session's own surface identity. The name/emoji come from
-// the agent-hello-ack cached on the WS; falls back to /auth/me for userId/org if the WS
-// ack hasn't landed yet. 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 {
-    const server = getServerUrl();
-    const editor = (process.env.DRAFTED_AGENT_NAME || '').trim() || null;
-    const base = {
-      server,
-      editor,
-      agentLabel: getAgentLabel(),
-      sessionId: agentSurface?.sessionId || getState().sessionId || null,
+// THIS-session surface identity: the session name + capital/color tile (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,
+      capital: agentSurface.capital,
+      color: agentSurface.color,
+      surfaced: true,
+      alive: !!agentSurface.alive,
     };
-    if (agentSurface) {
-      return ok({
-        ...base,
-        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 sid = base.sessionId || getBootstrapSessionId();
-    let me = null;
-    if (sid) {
-      try {
-        const res = await fetch(`${server}/auth/me`, { headers: { Cookie: `gc_session=${sid}` } });
-        if (res.ok) me = await res.json();
-      } catch { /* not yet authenticated */ }
-    }
+  }
+  // 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,
+    capital: null,
+    color: 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 (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({
-      ...base,
-      userId: me?.userId ?? null,
-      orgId: me?.currentOrg?.id ?? null,
-      projectId: getState().projectId ?? null,
-      name: null,
-      emoji: null,
-      surfaced: false,
-      alive: false,
+      server: getServerUrl(),
+      editor: (process.env.DRAFTED_AGENT_NAME || '').trim() || null,
+      agentLabel: getAgentLabel(),
+      ...(await sessionSurfaceBlock()),
     });
   } catch (error) { return err(error); }
 });
@@ -1566,7 +1579,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.'),
@@ -1695,7 +1708,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)));
       }
@@ -2134,12 +2147,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;
 
@@ -2164,7 +2178,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); }
 });
@@ -3098,7 +3113,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).'),
@@ -3320,7 +3335,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'),
@@ -3576,7 +3591,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.12.0",
+  "version": "1.12.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": [