@lucern/mcp 0.2.0-alpha.1 → 0.2.0-alpha.10

package/dist/runtime.d.ts

@@ -0,0 +1,111 @@
+import { AuthContext } from '@lucern/contracts';
+export { AuthContext } from '@lucern/contracts';
+import { ConvexHttpClient } from 'convex/browser';
+
+/**
+ * Handler Types — shared types for MCP tool handlers.
+ */
+
+/**
+ * An authenticated tool handler that receives session context as a second argument.
+ *
+ * New handlers should use this signature. Legacy handlers are adapted by the
+ * withAuth wrapper — the dispatch layer passes (args, ctx) but existing
+ * handlers only destructure args, silently ignoring ctx.
+ *
+ * Per Codex finding #7: context is passed via explicit (args, ctx) signature,
+ * NOT via args.__auth injection.
+ */
+type AuthenticatedHandler = (args: Record<string, unknown>, ctx: AuthContext) => Promise<Record<string, unknown>>;
+
+/**
+ * Handler Index — barrel file combining all handler modules into a single map.
+ *
+ * Each handler module exports a HandlerModule (Record<string, ToolHandler>)
+ * keyed by MCP tool name. buildHandlerMap() merges them into a single lookup.
+ */
+
+/**
+ * Build the complete handler map for all MCP tools.
+ */
+declare function buildHandlerMap(): Record<string, AuthenticatedHandler>;
+
+/**
+ * Write Policy — S2-13K Graph Compounding
+ *
+ * Policy enforcement for MCP mutation tools.
+ * Queries Convex write policies and tracks per-session write counts.
+ */
+
+/**
+ * Check if a tool name is a mutation (write) tool.
+ */
+declare function isMutationTool(toolName: string): boolean;
+/**
+ * Record a write operation for the current session.
+ */
+declare function recordWrite(toolName: string, topicId?: string, sessionId?: string): void;
+type PolicyCheckResult = {
+    allowed: boolean;
+    permission: string;
+    rationale?: string;
+    maxWritesPerSession?: number;
+    toolCategory?: string | null;
+    policy?: Record<string, unknown> | null;
+    explanation?: {
+        summary?: string;
+        matchedReasonCode?: string;
+        steps?: Array<{
+            stage?: string;
+            outcome?: string;
+            reasonCode?: string;
+            detail?: string;
+        }>;
+        [key: string]: unknown;
+    };
+    reason: string;
+};
+/**
+ * Check if a mutation tool call is allowed by write policy.
+ *
+ * Resolution order:
+ * 1. Topic-specific + role match
+ * 2. Global (no topic) + role match
+ * 3. No matching policy → allow (open by default)
+ *
+ * Also checks per-session write limits if policy specifies maxWritesPerSession.
+ */
+declare function checkWritePolicy(toolName: string, topicId: string | undefined, authCtx: AuthContext): Promise<PolicyCheckResult>;
+
+/**
+ * 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 };