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

package/dist/hosted-route.js

@@ -890,13 +890,31 @@ function mergeHeaderRecord(base, addition) {
   }
   return Object.fromEntries(headers.entries());
 }
+function cleanHeaderValue(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
 function createGatewayRequestClient(config = {}) {
   const fetchImpl = config.fetchImpl ?? fetch;
   const baseUrl = config.baseUrl?.replace(/\/+$/, "") ?? "";
   const maxRetries = config.maxRetries ?? 2;
   const requestIdFactory = config.requestIdFactory ?? (() => generatePortableRequestId());
   async function resolveAuthHeaders() {
-    const base = config.getAuthHeaders ? await config.getAuthHeaders() : {};
+    const provided = config.getAuthHeaders ? await config.getAuthHeaders() : {};
+    const headers = new Headers(provided);
+    const setIfAbsent = (name, value) => {
+      const normalized = cleanHeaderValue(value);
+      if (normalized && !headers.has(name)) {
+        headers.set(name, normalized);
+      }
+    };
+    setIfAbsent("x-lucern-key", config.apiKey);
+    setIfAbsent("x-lucern-session-token", config.userToken);
+    setIfAbsent("x-lucern-environment", config.environment);
+    setIfAbsent("x-lucern-clerk-id", config.clerkId);
+    setIfAbsent("x-lucern-user-id", config.userId ?? config.clerkId);
+    setIfAbsent("x-lucern-deployment-host", config.deploymentHost);
+    const base = Object.fromEntries(headers.entries());
     const authContextInput = await resolveConfiguredAuthContext(
       config.authContext
     );
@@ -2190,7 +2208,7 @@ function normalizeCanonicalPrincipalIdentity(input, options = {}) {
   })) {
     throw new LucernAccessControlError(
       "clerk_alias_unrecognized",
-      "Observed Clerk user id is not attached to the canonical Lucern principal."
+      "Observed Clerk user id does not match the canonical human principal id."
     );
   }
   return {
@@ -7792,7 +7810,7 @@ function createToolRegistryClient(config = {}) {
 }
 
 // ../sdk/src/version.ts
-var LUCERN_SDK_VERSION = "0.3.0-alpha.15";
+var LUCERN_SDK_VERSION = "0.3.0-alpha.17";
 
 // ../sdk/src/workflowClient.ts
 function normalizeLensQuery(value) {
@@ -8200,6 +8218,12 @@ function toGatewayConfig(config) {
   return {
     baseUrl: config.baseUrl,
     fetchImpl: config.fetchImpl,
+    apiKey: config.apiKey,
+    userToken: config.userToken,
+    environment: config.environment,
+    clerkId: config.clerkId,
+    userId: config.userId,
+    deploymentHost: config.deploymentHost,
     maxRetries: config.maxRetries,
     timeoutMs: config.timeoutMs,
     timeoutMsByMethod: config.timeoutMsByMethod,
@@ -8208,19 +8232,7 @@ function toGatewayConfig(config) {
     onResponse: config.onResponse,
     authContext: config.authContext,
     requireCanonicalAuthContext: config.requireCanonicalAuthContext,
-    getAuthHeaders: async () => {
-      const base = config.getAuthHeaders ? await config.getAuthHeaders() : {};
-      if (config.apiKey && !base["x-lucern-key"] && !base.Authorization) {
-        base["x-lucern-key"] = config.apiKey;
-      }
-      if (config.userToken && !base["x-lucern-session-token"]) {
-        base["x-lucern-session-token"] = config.userToken;
-      }
-      if (config.environment && !base["x-lucern-environment"]) {
-        base["x-lucern-environment"] = config.environment;
-      }
-      return base;
-    }
+    getAuthHeaders: config.getAuthHeaders
   };
 }
 function exposeGatewayData(response) {
@@ -11492,7 +11504,7 @@ var SESSION_LIFECYCLE_STATUSES = [
   "revoked"
 ];
 function inferSessionPrincipalType(principalId) {
-  if (principalId.startsWith("user:")) {
+  if (/^user_[A-Za-z0-9]+$/.test(principalId)) {
     return "human";
   }
   if (principalId.startsWith("agent:")) {
@@ -13975,7 +13987,7 @@ var IDENTITY_WHOAMI = {
   response: {
     description: "Canonical identity summary for the current session",
     fields: {
-      principalId: "string \u2014 canonical federated principal identifier",
+      principalId: "string \u2014 canonical principal identifier; for humans this is the Clerk user_... ID",
       principalType: "string \u2014 human, service, agent, group, or external_viewer",
       tenantId: "string | undefined \u2014 resolved tenant scope",
       workspaceId: "string | undefined \u2014 resolved workspace scope",
@@ -13989,7 +14001,7 @@ var IDENTITY_WHOAMI = {
 };
 var RESOLVE_INTERACTIVE_PRINCIPAL = {
   name: "resolve_interactive_principal",
-  description: "Read the Permit-backed Lucern principal context for an authenticated Clerk user. Like `git config --get user.email` plus the repository ACL \u2014 resolves the identity alias into the canonical authorization subject.",
+  description: "Read the Permit-backed Lucern principal context for an authenticated Clerk user. Like `git config --get user.email` plus the repository ACL \u2014 resolves the Clerk subject into tenant/workspace authorization context.",
   parameters: {
     clerkId: {
       type: "string",
@@ -14012,7 +14024,7 @@ var RESOLVE_INTERACTIVE_PRINCIPAL = {
   response: {
     description: "Permit-backed Lucern principal context for tenant SDK bootstrap",
     fields: {
-      principalId: "string \u2014 canonical Lucern principal identifier",
+      principalId: "string \u2014 canonical Clerk user_... ID for human sessions",
       principalType: "string \u2014 human, service, agent, group, or external_viewer",
       clerkId: "string \u2014 authenticated Clerk subject alias",
       tenantId: "string \u2014 resolved tenant scope",
@@ -14840,7 +14852,7 @@ var MANAGE_WRITE_POLICY = {
     },
     role: {
       type: "string",
-      description: "Role to set policy for (required for 'set'). E.g. 'agent:internal', 'user:analyst'."
+      description: "Role to set policy for (required for 'set'). E.g. 'agent:internal' or a Permit role key such as 'workspace_admin'."
     },
     permission: {
       type: "string",
@@ -17893,6 +17905,7 @@ defineTable({
   shape: z.object({
     "tenantId": idOf("tenants"),
     "workspaceId": idOf("workspaces").optional(),
+    "environment": z.enum(["dev", "staging", "prod"]).optional(),
     "keyPrefix": z.enum(["luc", "stk"]),
     "keyHash": z.string(),
     "keyHint": z.string(),
@@ -17920,7 +17933,7 @@ defineTable({
   shape: z.object({
     "tenantId": idOf("tenants").optional(),
     "apiKeyId": idOf("apiKeys").optional(),
-    "action": z.enum(["key_created", "key_revoked", "key_expired", "key_used", "tenant_secret_created", "tenant_secret_rotated", "tenant_secret_revoked", "tenant_slot_binding_upserted", "tenant_slot_binding_revoked", "proxy_token_minted", "proxy_token_lease_issued", "proxy_token_lease_renewed", "proxy_token_lease_revoked", "proxy_request_recorded", "tenant_created", "tenant_updated", "tenant_suspended", "tenant_archived", "tenant_reactivated", "principal_created", "principal_updated", "principal_suspended", "principal_identity_alias_upserted", "principal_identity_alias_revoked", "membership_created", "membership_updated", "membership_revoked", "group_created", "group_updated", "group_deleted", "group_member_added", "group_member_removed", "workspace_created", "workspace_updated", "workspace_archived", "workspace_deployment_set", "workspace_deployment_removed", "deployment_host_registered", "deployment_host_revoked", "service_key_created", "service_key_rotated", "service_key_revoked", "service_key_used", "service_key_auth_failed", "session_created", "session_validated", "session_revoked", "session_cascade_revoked", "session_expired", "sandbox_created", "sandbox_secret_injected", "sandbox_execution_started", "sandbox_execution_completed", "sandbox_limit_violated", "policy_created", "policy_updated", "policy_enforced", "policy_archived", "permit_sync_enqueued", "permit_sync_succeeded", "permit_sync_failed", "permit_sync_skipped", "agent_registered", "agent_updated", "tool_registered", "tool_updated", "pack_entitled", "pack_installed", "pack_enabled", "pack_disabled", "pack_entitlement_revoked", "pack_upgraded", "pack_upgrade_committed", "pack_upgrade_rolled_back", "pack_group_assigned", "pack_group_unassigned", "methodology_pack_created", "methodology_pack_updated", "methodology_pack_assigned", "methodology_pack_removed", "pack_assigned_to_group", "pack_revoked_from_group", "pack_ontology_materialized", "pack_ontology_topic_bound", "cutover_flag_set", "cutover_flag_cleared"]),
+    "action": z.enum(["key_created", "key_revoked", "key_expired", "key_used", "tenant_secret_created", "tenant_secret_rotated", "tenant_secret_revoked", "tenant_slot_binding_upserted", "tenant_slot_binding_revoked", "proxy_token_minted", "proxy_token_lease_issued", "proxy_token_lease_renewed", "proxy_token_lease_revoked", "proxy_request_recorded", "tenant_created", "tenant_updated", "tenant_suspended", "tenant_archived", "tenant_reactivated", "tenant_clerk_organization_linked", "principal_created", "principal_updated", "principal_suspended", "principal_identity_alias_upserted", "principal_identity_alias_revoked", "membership_created", "membership_updated", "membership_revoked", "group_created", "group_updated", "group_deleted", "group_member_added", "group_member_removed", "workspace_created", "workspace_updated", "workspace_archived", "workspace_deployment_set", "workspace_deployment_removed", "deployment_host_registered", "deployment_host_revoked", "service_key_created", "service_key_rotated", "service_key_revoked", "service_key_used", "service_key_auth_failed", "session_created", "session_validated", "session_revoked", "session_cascade_revoked", "session_expired", "sandbox_created", "sandbox_secret_injected", "sandbox_execution_started", "sandbox_execution_completed", "sandbox_limit_violated", "policy_created", "policy_updated", "policy_enforced", "policy_archived", "permit_sync_enqueued", "permit_sync_succeeded", "permit_sync_failed", "permit_sync_skipped", "agent_registered", "agent_updated", "tool_registered", "tool_updated", "pack_entitled", "pack_installed", "pack_enabled", "pack_disabled", "pack_entitlement_revoked", "pack_upgraded", "pack_upgrade_committed", "pack_upgrade_rolled_back", "pack_group_assigned", "pack_group_unassigned", "methodology_pack_created", "methodology_pack_updated", "methodology_pack_assigned", "methodology_pack_removed", "pack_assigned_to_group", "pack_revoked_from_group", "pack_ontology_materialized", "pack_ontology_topic_bound", "cutover_flag_set", "cutover_flag_cleared"]),
     "actorClerkId": z.string(),
     "details": z.any().optional(),
     "createdAt": z.number()
@@ -23131,6 +23144,21 @@ var INFISICAL_RUNTIME_PATHS = [
       }
     ]
   },
+  {
+    id: "platform-operator-credentials",
+    secretPath: "/platform/runtime",
+    description: "Lucern-owned operator credential material for local CLI, MCP, and SDK sessions.",
+    variables: [
+      {
+        name: "LUCERN_API_KEY",
+        required: false,
+        secret: true,
+        public: false,
+        aliases: ["LUCERN_KEY"],
+        description: "Lucern-owned operator API key for gateway calls from trusted local tooling."
+      }
+    ]
+  },
   {
     id: "tenant-shared-install",
     secretPath: TENANT_CLIENT_INSTALL_TOKEN_INFISICAL_PATH,
@@ -23166,7 +23194,7 @@ var INFISICAL_RUNTIME_SURFACES = [
     id: "lucern-sdk",
     packageName: "@lucern/sdk",
     delivery: "runtime_fetch",
-    sourcePathIds: ["platform-runtime"],
+    sourcePathIds: ["platform-runtime", "platform-operator-credentials"],
     consumer: "server-side SDK operator contexts with a scoped Infisical identity",
     description: "SDK exposes the runtime Infisical resolver used by clients that have machine identity credentials."
   },
@@ -23175,7 +23203,7 @@ var INFISICAL_RUNTIME_SURFACES = [
     packageName: "@lucern/cli",
     delivery: "runtime_fetch",
     fallback: "device_auth",
-    sourcePathIds: ["platform-runtime"],
+    sourcePathIds: ["platform-runtime", "platform-operator-credentials"],
     consumer: "developer/operator CLI processes",
     description: "CLI hydrates runtime defaults from Infisical when configured, then authenticates users through Lucern device login."
   },
@@ -23184,7 +23212,7 @@ var INFISICAL_RUNTIME_SURFACES = [
     packageName: "@lucern/mcp",
     delivery: "runtime_fetch",
     fallback: "device_auth",
-    sourcePathIds: ["platform-runtime"],
+    sourcePathIds: ["platform-runtime", "platform-operator-credentials"],
     consumer: "MCP server/client processes",
     description: "MCP hydrates runtime defaults through the SDK resolver and remains a Lucern client, not a platform secret owner."
   },
@@ -25665,9 +25693,33 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
       "consumer": "server-side SDK operator contexts with a scoped Infisical identity",
       "description": "SDK exposes the runtime Infisical resolver used by clients that have machine identity credentials.",
       "sourcePathIds": [
-        "platform-runtime"
+        "platform-runtime",
+        "platform-operator-credentials"
       ],
       "variables": [
+        {
+          "canonicalName": "LUCERN_API_KEY",
+          "envNames": [
+            "LUCERN_API_KEY",
+            "LUCERN_KEY"
+          ],
+          "aliases": [
+            "LUCERN_KEY"
+          ],
+          "writeNames": [
+            "LUCERN_API_KEY"
+          ],
+          "required": false,
+          "secret": true,
+          "public": false,
+          "sourcePath": "/platform/runtime",
+          "environmentPolicy": "environment_specific",
+          "consumers": [
+            "lucern-sdk"
+          ],
+          "destinations": [],
+          "description": "Lucern-owned operator API key for gateway calls from trusted local tooling."
+        },
         {
           "canonicalName": "LUCERN_API_URL",
           "envNames": [
@@ -25768,9 +25820,57 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
       "consumer": "developer/operator CLI processes",
       "description": "CLI hydrates runtime defaults from Infisical when configured, then authenticates users through Lucern device login.",
       "sourcePathIds": [
-        "platform-runtime"
+        "platform-runtime",
+        "platform-operator-credentials"
       ],
       "variables": [
+        {
+          "canonicalName": "LUCERN_API_KEY",
+          "envNames": [
+            "LUCERN_API_KEY",
+            "LUCERN_KEY"
+          ],
+          "aliases": [
+            "LUCERN_KEY"
+          ],
+          "writeNames": [
+            "LUCERN_API_KEY"
+          ],
+          "required": false,
+          "secret": true,
+          "public": false,
+          "sourcePath": "/platform/runtime",
+          "environmentPolicy": "environment_specific",
+          "consumers": [
+            "lucern-cli",
+            "lucern-mcp",
+            "lucern-repo-ci"
+          ],
+          "destinations": [
+            {
+              "kind": "runtime_fetch",
+              "target": "lucern-cli-mcp-sdk",
+              "writeNames": [
+                "LUCERN_API_KEY"
+              ]
+            },
+            {
+              "kind": "operator_local",
+              "target": "lucern-repo",
+              "writeNames": [
+                "LUCERN_API_KEY"
+              ]
+            },
+            {
+              "kind": "github_actions",
+              "target": "LucernAI/lucern",
+              "writeNames": [
+                "LUCERN_API_KEY"
+              ]
+            }
+          ],
+          "description": "Lucern-owned operator API key for gateway calls from trusted local tooling. Lucern-owned operator API key for trusted CLI/MCP/CI calls. Source it from /platform/runtime; do not persist it into local user credential files."
+        },
         {
           "canonicalName": "LUCERN_API_URL",
           "envNames": [
@@ -26109,7 +26209,8 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
       "consumer": "MCP server/client processes",
       "description": "MCP hydrates runtime defaults through the SDK resolver and remains a Lucern client, not a platform secret owner.",
       "sourcePathIds": [
-        "platform-runtime"
+        "platform-runtime",
+        "platform-operator-credentials"
       ],
       "variables": [
         {
@@ -26197,6 +26298,53 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
           ],
           "description": "Lucern-owned Clerk backend secret. Never route to tenant-owned apps unless that tenant is Lucern itself."
         },
+        {
+          "canonicalName": "LUCERN_API_KEY",
+          "envNames": [
+            "LUCERN_API_KEY",
+            "LUCERN_KEY"
+          ],
+          "aliases": [
+            "LUCERN_KEY"
+          ],
+          "writeNames": [
+            "LUCERN_API_KEY"
+          ],
+          "required": false,
+          "secret": true,
+          "public": false,
+          "sourcePath": "/platform/runtime",
+          "environmentPolicy": "environment_specific",
+          "consumers": [
+            "lucern-cli",
+            "lucern-mcp",
+            "lucern-repo-ci"
+          ],
+          "destinations": [
+            {
+              "kind": "runtime_fetch",
+              "target": "lucern-cli-mcp-sdk",
+              "writeNames": [
+                "LUCERN_API_KEY"
+              ]
+            },
+            {
+              "kind": "operator_local",
+              "target": "lucern-repo",
+              "writeNames": [
+                "LUCERN_API_KEY"
+              ]
+            },
+            {
+              "kind": "github_actions",
+              "target": "LucernAI/lucern",
+              "writeNames": [
+                "LUCERN_API_KEY"
+              ]
+            }
+          ],
+          "description": "Lucern-owned operator API key for gateway calls from trusted local tooling. Lucern-owned operator API key for trusted CLI/MCP/CI calls. Source it from /platform/runtime; do not persist it into local user credential files."
+        },
         {
           "canonicalName": "LUCERN_API_URL",
           "envNames": [
@@ -26937,7 +27085,7 @@ function compactRecord2(input) {
     Object.entries(input).filter(([, value]) => value !== void 0)
   );
 }
-var listBeliefsProjection = defineProjection({
+defineProjection({
   contractName: "list_beliefs",
   inputSchema: listBeliefsInputSchema,
   project: (input) => compactRecord2({
@@ -27566,11 +27714,8 @@ var identityContracts = [
     sdkNamespace: "identity",
     sdkMethod: "whoami",
     summary: "Describe the current gateway principal.",
-    convex: {
-      module: "identity",
-      functionName: "whoami",
-      kind: "query",
-      inputProjection: withPrincipal
+    gateway: {
+      handler: "identity.whoami"
     }
   }),
   surfaceContract({
@@ -27590,7 +27735,7 @@ var identityContracts = [
       providerProjectId: z.string().min(1).optional()
     }),
     convex: {
-      module: "identity",
+      module: "platform",
       functionName: "resolveInteractivePrincipal",
       kind: "query"
     }
@@ -27674,15 +27819,6 @@ var beliefLookupInput = (input) => compactRecord4({
 var beliefNodeInput = (input) => compactRecord4({
   nodeId: input.nodeId ?? input.id ?? input.beliefId
 });
-var beliefTopicInput = (input) => {
-  const parsed = listBeliefsProjection.inputSchema.safeParse(input);
-  if (!parsed.success) {
-    throw new Error(
-      `list_beliefs projection input rejected: ${parsed.error.message}`
-    );
-  }
-  return compactRecord4(listBeliefsProjection.project(parsed.data));
-};
 var createBeliefInput = (input, context) => {
   return withUserId(
     compactRecord4({
@@ -27771,11 +27907,8 @@ var beliefsContracts = [
     sdkNamespace: "beliefs",
     sdkMethod: "listBeliefs",
     summary: "List beliefs for a topic.",
-    convex: {
-      module: "beliefs",
-      functionName: "getByTopic",
-      kind: "query",
-      inputProjection: beliefTopicInput
+    gateway: {
+      handler: "beliefs.list"
     },
     args: listBeliefsInputSchema
   }),
@@ -27960,12 +28093,6 @@ var evidenceIdInput = (input) => compactRecord4({
   insightId: input.insightId,
   nodeId: input.nodeId ?? input.id ?? input.evidenceId
 });
-var evidenceTopicInput = (input) => compactRecord4({
-  topicId: input.topicId,
-  status: input.status,
-  userId: input.userId,
-  limit: input.limit
-});
 var createEvidenceInput = (input, context) => {
   const parsed = createEvidenceProjection.inputSchema.safeParse(input);
   if (!parsed.success) {
@@ -28096,11 +28223,8 @@ var evidenceContracts = [
     sdkNamespace: "evidence",
     sdkMethod: "listEvidence",
     summary: "List evidence for a topic.",
-    convex: {
-      module: "evidence",
-      functionName: "getByTopic",
-      kind: "query",
-      inputProjection: evidenceTopicInput
+    gateway: {
+      handler: "evidence.list"
     }
   }),
   surfaceContract({
@@ -28335,11 +28459,8 @@ var questionsContracts = [
     sdkNamespace: "questions",
     sdkMethod: "listQuestions",
     summary: "List questions for a topic.",
-    convex: {
-      module: "questions",
-      functionName: "getByTopic",
-      kind: "query",
-      inputProjection: questionTopicInput
+    gateway: {
+      handler: "questions.list"
     }
   }),
   surfaceContract({
@@ -29444,6 +29565,19 @@ var worktreeEvidenceSignalInputSchema = z.object({
   progress: z.string().optional().describe("Collection progress note for the signal."),
   notes: z.string().optional().describe("Additional evidence collection notes.")
 }).passthrough().describe("Evidence signal embedded in the worktree plan.");
+var worktreeDocCompanionTargetSchema = z.object({
+  docPath: z.string().describe(
+    "Repo-relative path to a documentation file the worktree promises to update."
+  ),
+  sectionAnchor: z.string().optional().describe(
+    "Markdown heading anchor (e.g. '## Function-surface manifest') that scopes the promised update."
+  ),
+  reason: z.string().describe(
+    "Why this doc section must be updated for the worktree to be complete."
+  )
+}).passthrough().describe(
+  "Intent-driven docs companion target. pr-gate-reviewer verifies that the PR actually touches each declared (docPath, sectionAnchor). Distinct from the touch-driven docs-loop. See docs/development/docs-sync-discipline.md Lock 3."
+);
 var worktreeDecisionGateInputSchema = z.object({
   goCriteria: z.array(z.string()).describe("Criteria that must hold for the worktree to proceed."),
   noGoSignals: z.array(z.string()).describe("Signals that stop or redirect the worktree."),
@@ -29476,6 +29610,9 @@ var addWorktreeArgs = z.object({
   keyQuestions: z.array(worktreeKeyQuestionInputSchema).optional().describe("Inline key questions captured as part of the worktree plan."),
   evidenceSignals: z.array(worktreeEvidenceSignalInputSchema).optional().describe("Evidence signals the worktree needs to collect or validate."),
   decisionGate: worktreeDecisionGateInputSchema.optional(),
+  docCompanionTargets: z.array(worktreeDocCompanionTargetSchema).optional().describe(
+    "Doc sections the worktree promises to update at PR time. Enforced by pr-gate-reviewer (Lock 3)."
+  ),
   goCriteria: z.array(z.string()).optional().describe("Shorthand go criteria used to build decisionGate."),
   noGoSignals: z.array(z.string()).optional().describe("Shorthand no-go signals used to build decisionGate."),
   proofArtifacts: z.array(z.unknown()).optional().describe("Expected proof artifacts required to close the worktree."),
@@ -34658,7 +34795,7 @@ function createLucernStandaloneMcpServer(options) {
   });
   const server = new McpServer({
     name: "lucern-mcp",
-    version: "0.3.0-alpha.15"
+    version: "0.3.0-alpha.17"
   });
   registerTools(server, runtime);
   const resources = registerResources(server, runtime, observationStore);