feat(sdk): ensure sdk clients are not global, change open() to return document handle (#2497)

* fix(sdk): prevent cross-document contamination across multi-client sessions

* chore: additional docs fixes

Author: harbournick

apps/cli/scripts/export-sdk-contract.ts

@@ -31,6 +31,22 @@ import type { CliOnlyOperation } from '../src/cli/types';
 import { CLI_ONLY_OPERATION_DEFINITIONS } from '../src/cli/cli-only-operation-definitions';
 import { HOST_PROTOCOL_VERSION, HOST_PROTOCOL_FEATURES, HOST_PROTOCOL_NOTIFICATIONS } from '../src/host/protocol';
 
+// ---------------------------------------------------------------------------
+// SDK surface classification
+// ---------------------------------------------------------------------------
+
+type SdkSurface = 'client' | 'document' | 'internal';
+
+const CLIENT_OPERATIONS = new Set(['doc.open', 'doc.describe', 'doc.describeCommand']);
+const INTERNAL_OPERATIONS = new Set(['doc.status']);
+
+function classifySdkSurface(operationId: string): SdkSurface {
+  if (CLIENT_OPERATIONS.has(operationId)) return 'client';
+  if (INTERNAL_OPERATIONS.has(operationId)) return 'internal';
+  if (operationId.startsWith('doc.session.')) return 'internal';
+  return 'document';
+}
+
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
@@ -81,6 +97,7 @@ function buildSdkContract() {
     // Base fields shared by all operations
     const entry: Record<string, unknown> = {
       operationId: cliOpId,
+      sdkSurface: classifySdkSurface(cliOpId),
       command: metadata.command,
       commandTokens: [...cliCommandTokens(cliOpId)],
       category: cliCategory(cliOpId),

apps/cli/src/commands/close.ts

@@ -31,8 +31,6 @@ export async function runClose(tokens: string[], context: CommandContext): Promi
     'close',
     async ({ metadata, paths }) => {
       const effectiveMetadata = metadata;
-      const activeSessionId = await getActiveSessionId();
-      const wasDefaultSession = activeSessionId === effectiveMetadata.contextId;
 
       if (effectiveMetadata.dirty && !mode.discard) {
         throw new CliError(
@@ -44,6 +42,15 @@ export async function runClose(tokens: string[], context: CommandContext): Promi
         );
       }
 
+      // Only read/clear the project-global active-session pointer in oneshot
+      // (CLI) mode. Host mode must never touch this file — it causes
+      // cross-document contamination between SDK clients.
+      let wasDefaultSession = false;
+      if (context.executionMode !== 'host') {
+        const activeSessionId = await getActiveSessionId();
+        wasDefaultSession = activeSessionId === effectiveMetadata.contextId;
+      }
+
       const result = {
         command: 'close',
         data: {
@@ -74,5 +81,6 @@ export async function runClose(tokens: string[], context: CommandContext): Promi
       return result;
     },
     context.sessionId,
+    context.executionMode,
   );
 }

apps/cli/src/commands/open.ts

@@ -178,7 +178,7 @@ export async function runOpen(tokens: string[], context: CommandContext): Promis
       const bootstrap = 'bootstrap' in opened ? opened.bootstrap : undefined;
       let adoptedToHostPool = false;
       try {
-        const output = await exportToPath(opened.editor, paths.workingDocPath, true);
+        await exportToPath(opened.editor, paths.workingDocPath, true);
         const sourcePath =
           opened.meta.source === 'path' && opened.meta.path
             ? resolveSourcePathForMetadata(opened.meta.path)
@@ -195,7 +195,13 @@ export async function runOpen(tokens: string[], context: CommandContext): Promis
         });
 
         await writeContextMetadata(paths, metadata);
-        await setActiveSessionId(metadata.contextId);
+
+        // Only update the project-global active-session pointer in oneshot (CLI) mode.
+        // Host mode must never write this file — it causes cross-document contamination
+        // when multiple SDK clients share the same project root.
+        if (context.executionMode !== 'host') {
+          await setActiveSessionId(metadata.contextId);
+        }
 
         if (context.executionMode === 'host' && context.sessionPool) {
           context.sessionPool.adoptFromOpen(sessionId, opened, {

apps/cli/src/commands/save.ts

@@ -140,5 +140,6 @@ export async function runSave(tokens: string[], context: CommandContext): Promis
       };
     },
     context.sessionId,
+    context.executionMode,
   );
 }

apps/cli/src/lib/context.ts

@@ -8,7 +8,7 @@ import { CliError } from './errors';
 import { asRecord, pathExists } from './guards';
 import type { CollaborationProfile } from './collaboration';
 import { validateSessionId } from './session';
-import type { CliIO, UserIdentity } from './types';
+import type { CliIO, ExecutionMode, UserIdentity } from './types';
 
 const CONTEXT_VERSION = 'v1';
 const ACTIVE_SESSION_FILENAME = 'active-session';
@@ -538,16 +538,44 @@ export async function clearContext(paths: ContextPaths): Promise<void> {
   await rm(paths.contextDir, { recursive: true, force: true });
 }
 
+/**
+ * Resolve the target session id for an operation, respecting execution mode.
+ *
+ * - If an explicit session id is provided, return it immediately.
+ * - In host mode, an explicit session id is **required** — never fall back to
+ *   the project-global active-session file. This prevents cross-document
+ *   contamination between SDK clients sharing the same project root.
+ * - In oneshot (CLI) mode, fall back to the active-session file as a
+ *   convenience for single-terminal workflows.
+ */
+export async function resolveSessionId(
+  sessionId: string | undefined,
+  executionMode: ExecutionMode | undefined,
+): Promise<string> {
+  if (sessionId) return sessionId;
+
+  if (executionMode === 'host') {
+    throw new CliError(
+      'SESSION_REQUIRED',
+      'Host-mode operations require an explicit session id. Use the SDK document handle or pass --session.',
+    );
+  }
+
+  const activeSessionId = await getActiveSessionId();
+  if (!activeSessionId) {
+    throw new CliError('NO_ACTIVE_DOCUMENT', 'No active document. Run "superdoc open <doc>" first.');
+  }
+  return activeSessionId;
+}
+
 export async function withActiveContext<T>(
   io: CliIO,
   command: string,
   action: (state: { metadata: ContextMetadata; paths: ContextPaths }) => Promise<T>,
   contextId?: string,
+  executionMode?: ExecutionMode,
 ): Promise<T> {
-  const resolvedContextId = contextId ?? (await getActiveSessionId());
-  if (!resolvedContextId) {
-    throw new CliError('NO_ACTIVE_DOCUMENT', 'No active document. Run "superdoc open <doc>" first.');
-  }
+  const resolvedContextId = await resolveSessionId(contextId, executionMode);
 
   return withContextLock(
     io,

apps/cli/src/lib/errors.ts

@@ -2,6 +2,7 @@ export type CliErrorCode =
   | 'INVALID_ARGUMENT'
   | 'SESSION_ID_INVALID'
   | 'SESSION_NOT_FOUND'
+  | 'SESSION_REQUIRED'
   | 'UNKNOWN_COMMAND'
   | 'VALIDATION_ERROR'
   | 'MISSING_REQUIRED'

apps/cli/src/lib/introspection-dispatch.ts

@@ -226,7 +226,9 @@ const INTROSPECTION_INVOKERS: Partial<Record<CliOperationId, IntrospectionInvoke
   },
 
   'doc.status': async (_input, context) => {
-    const activeSessionId = await getActiveSessionId();
+    // In host mode, do not read or report the project-global active session id.
+    // It is a CLI-only convenience and has no meaning in host/SDK execution.
+    const activeSessionId = context.executionMode === 'host' ? null : await getActiveSessionId();
 
     try {
       return await withActiveContext(
@@ -273,9 +275,10 @@ const INTROSPECTION_INVOKERS: Partial<Record<CliOperationId, IntrospectionInvoke
           };
         },
         context.sessionId,
+        context.executionMode,
       );
     } catch (error) {
-      if (error instanceof CliError && error.code === 'NO_ACTIVE_DOCUMENT') {
+      if (error instanceof CliError && (error.code === 'NO_ACTIVE_DOCUMENT' || error.code === 'SESSION_REQUIRED')) {
         return {
           command: 'status',
           data: {

apps/cli/src/lib/mutation-orchestrator.ts

@@ -284,5 +284,6 @@ export async function executeMutationOperation(request: DocOperationRequest): Pr
       }
     },
     context.sessionId,
+    context.executionMode,
   );
 }

apps/cli/src/lib/operation-executor.ts

@@ -1,4 +1,4 @@
-import { getActiveSessionId } from './context';
+import { resolveSessionId } from './context';
 import { CliError } from './errors';
 import { isRecord } from './guards';
 import { hasNonEmptyString } from './input-readers';
@@ -172,10 +172,9 @@ async function preflightCallContext(
     return;
   }
 
-  const activeSessionId = await getActiveSessionId();
-  if (!hasNonEmptyString(activeSessionId)) {
-    throw new CliError('NO_ACTIVE_DOCUMENT', `call: ${operationId} requires an active session or input.sessionId.`);
-  }
+  // Delegates to the centralized resolver: host mode hard-fails without an
+  // explicit session id; oneshot mode falls back to the active-session file.
+  await resolveSessionId(undefined, context.executionMode);
 }
 
 // ---------------------------------------------------------------------------

apps/cli/src/lib/read-orchestrator.ts

@@ -169,5 +169,6 @@ export async function executeReadOperation(request: DocOperationRequest): Promis
       }
     },
     context.sessionId,
+    context.executionMode,
   );
 }