@lucern/mcp 0.3.0-alpha.17 → 0.3.0-alpha.2

package/dist/runtime.d.ts

@@ -1,5 +1,6 @@
 import { AuthContext } from '@lucern/contracts';
 export { AuthContext } from '@lucern/contracts';
+import { ConvexHttpClient } from 'convex/browser';
 
 /**
  * Handler Types — shared types for MCP tool handlers.
@@ -33,13 +34,13 @@ declare function buildHandlerMap(): Record<string, AuthenticatedHandler>;
  * Write Policy — S2-13K Graph Compounding
  *
  * Policy enforcement for MCP mutation tools.
- * Queries gateway-owned write policies and tracks per-session write counts.
+ * Queries Convex write policies and tracks per-session write counts.
  */
 
 /**
  * Check if a tool name is a mutation (write) tool.
  */
-declare const isMutationTool: (toolName: string) => boolean;
+declare function isMutationTool(toolName: string): boolean;
 /**
  * Record a write operation for the current session.
  */
@@ -76,4 +77,35 @@ type PolicyCheckResult = {
  */
 declare function checkWritePolicy(toolName: string, topicId: string | undefined, authCtx: AuthContext): Promise<PolicyCheckResult>;
 
-export { type AuthenticatedHandler, buildHandlerMap, checkWritePolicy, isMutationTool, recordWrite };
+/**
+ * Convex Clients — Lazy-initialized admin-authed ConvexHttpClients for MCP server.
+ *
+ * LAZY INITIALIZATION: Clients are created on first use, not at import time.
+ * This allows index.ts loadLucernEnv() to decode LUCERN_API_KEY and
+ * STACK_API_KEY into their respective URL and deploy key env vars before
+ * any Convex calls are made.
+ *
+ * Three clients:
+ *   - Lucern client         → reasoning graph (good-blackbird / precious-dog) [required]
+ *   - Stack client          → StackOS platform (sincere-shepherd / sleek-mink) [optional]
+ *   - Master Control client → control plane (utmost-ox / successful-clam) [optional]
+ *
+ * Lucern + Stack are decoded from API keys by index.ts resolveCredentials() at startup.
+ * Master Control is resolved from MC_CONVEX_URL + MC_DEPLOY_KEY (set in ~/.lucern/credentials).
+ * Uses deploy key auth to call internal mutations/queries directly,
+ * bypassing Clerk (standard Convex server-to-server pattern).
+ */
+
+/**
+ * Run a function with a request-scoped Convex client.
+ * All `adminQuery`/`adminMutation`/`adminAction` calls within `fn` will
+ * use the provided client instead of the process-level singleton.
+ */
+declare function runWithScopedClient<T>(client: ConvexHttpClient, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Create an admin-authed ConvexHttpClient for a specific deployment.
+ * Used by the hosted route to create per-instance clients.
+ */
+declare function createAdminClient(url: string, deployKey: string): ConvexHttpClient;
+
+export { type AuthenticatedHandler, buildHandlerMap, checkWritePolicy, createAdminClient, isMutationTool, recordWrite, runWithScopedClient };