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

package/README.md

@@ -85,7 +85,8 @@ This package is the **external package MCP** surface (`packages/mcp`) intended f
 
 It is intentionally separate from the **internal Convex MCP** runtime under `convex/mcp/*` used by StackOS internals.
 
-See `docs/lucern-replatform/api/mcp-surface-separation.md` for boundary details.
+See `docs/reference/mcp-event-packages.md` for package-boundary details and
+`docs/reference/mcp.md` for the generated callable MCP inventory.
 
 ## Claude Code config
 

package/dist/cli.js

@@ -130,13 +130,9 @@ function loadProfile(options) {
   const localEnv = options.readLocalEnv === false ? {} : readLocalEnvFiles(options.cwd);
   const mergedEnv = { ...localEnv, ...options.env };
   const envProfile = profileFromEnvironment(mergedEnv);
-  const hasEnvCredentials = Boolean(
-    envProfile.apiKey || envProfile.userToken || envProfile.packKey
-  );
-  const explicitProfileSelected = options.profileName !== void 0 || mergedEnv.LUCERN_PROFILE !== void 0;
   const selectedProfile = options.profileName ?? mergedEnv.LUCERN_PROFILE ?? profiles.activeProfile ?? credentials.LUCERN_PROFILE ?? "default";
-  const selected = hasEnvCredentials && !explicitProfileSelected ? "env" : selectedProfile;
-  const savedProfile = hasEnvCredentials && !explicitProfileSelected ? {} : profiles.profiles?.[selectedProfile] ?? {};
+  const selected = selectedProfile;
+  const savedProfile = profiles.profiles?.[selectedProfile] ?? {};
   const credentialsProfile = {
     apiKey: credentials.LUCERN_API_KEY,
     userToken: readFirst(credentials, ["LUCERN_SESSION_TOKEN", "LUCERN_USER_TOKEN"]),
@@ -1198,7 +1194,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()
@@ -6409,6 +6405,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,
@@ -6444,7 +6455,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."
   },
@@ -6453,7 +6464,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."
   },
@@ -6462,7 +6473,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."
   },
@@ -8943,9 +8954,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": [
@@ -9046,9 +9081,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": [
@@ -9387,7 +9470,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": [
         {
@@ -9475,6 +9559,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": [
@@ -12724,7 +12855,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",
@@ -12738,7 +12869,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",
@@ -12761,7 +12892,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",
@@ -13589,7 +13720,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",
@@ -17382,6 +17513,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."),
@@ -17414,6 +17558,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."),
@@ -22432,7 +22579,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 {
@@ -28034,7 +28181,7 @@ function createToolRegistryClient(config = {}) {
 }
 
 // ../sdk/src/version.ts
-var LUCERN_SDK_VERSION = "0.3.0-alpha.16";
+var LUCERN_SDK_VERSION = "0.3.0-alpha.17";
 
 // ../sdk/src/workflowClient.ts
 function normalizeLensQuery(value) {
@@ -31728,7 +31875,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:")) {
@@ -34955,7 +35102,7 @@ function createLucernStandaloneMcpServer(options) {
   });
   const server = new McpServer({
     name: "lucern-mcp",
-    version: "0.3.0-alpha.16"
+    version: "0.3.0-alpha.17"
   });
   registerTools(server, runtime);
   const resources = registerResources(server, runtime, observationStore);