@firfi/huly-mcp 0.30.1 → 0.31.1

package/README.md

@@ -269,7 +269,7 @@ The roadmap is driven by SDK parity and the project principle that this server s
 
 Highest-value additions for coding agents:
 
-- Generic space follow-ups: role assignment mutations, role/permission definition writes, generic space creation, and module-specific wrappers above the shared space foundation.
+- Generic space follow-ups: role/permission definition writes, generic space creation, and module-specific wrappers above the shared space foundation. Generic space metadata, member/owner mutations, and typed-space role member mutations are covered by the shared spaces tools.
 - SDK discovery phase 2: space types, roles, permissions, plugin configuration, sequence metadata, and richer tool hints.
 - Drive follow-ups: drive create/update/delete, item move/rename/delete, adding new versions to existing files, permissions, and comments/activity.
 - Planner/ToDos: personal and project ToDo CRUD, scheduling, complete/reopen, priority, privacy/visibility, and document action items.
@@ -298,7 +298,7 @@ Planned feature surfaces:
 - Chat and communication: direct-message send/update/delete, group DMs, channel member mutations, join/leave/request access, archive/unarchive, star/favorite channels, close/reopen conversations, pinned messages, message attachments, translation, applets, in-message polls, and guest communication settings.
 - Notifications and activity: browser/push subscription internals, provider defaults, UI presenter/viewlet metadata, and activity control/extension metadata.
 - Attachments and media: previews/preview metadata and friendly wrappers for additional object types beyond issue/document.
-- Core schema and workspace administration: attribute/property create/update/delete/hide, enum CRUD/options, sequence management, role assignment mutations, role/permission definition writes, generic space creation, global space admins, integrations registry, invite settings, role capability settings, and workspace setting metadata.
+- Core schema and workspace administration: attribute/property create/update/delete/hide, enum CRUD/options, sequence management, role/permission definition writes, generic space creation, global space admins, integrations registry, invite settings, role capability settings, and workspace setting metadata.
 - Integrations: GitHub repository/project mappings and sync metadata (deferred), Google Calendar connect/configure/sync controls, Bitrix entity/field mappings and sync status, Gmail/email channel messages, Telegram messages, Huly Mail/Mail plugin behavior, AI assistant integration state, and AI bot configuration if server-side APIs expose stable behavior.
 - Templates, rating, support, billing, analytics, views, workbench, and preferences: message templates/categories/fields, document/person rating data blocked by unpublished `@hcengineering/rating` SDK package (#90), support conversations, billing tier/status discovery, onboarding channels, saved filtered views, user view preferences, tabs/widgets/apps, and module preference discovery/update.
 - Document-specific gaps: snapshot restore, backlinks, notes, structured action items/tables, PDF/export, advanced document relationships, and document printing/export once SDK support is safe.
@@ -489,6 +489,7 @@ SDK upgrade revisit:
 | `update_channel` | Update fields on an existing Huly channel. Only provided fields are modified. |
 | `delete_channel` | Permanently delete a Huly channel. This action cannot be undone. For reversible channel lifecycle changes, use archive_channel and unarchive_channel instead. |
 | `list_channel_messages` | List messages in a Huly channel. Returns messages sorted by date (newest first). |
+| `list_external_channel_messages` | List read-only messages for an external Gmail or Telegram channel by channel name or ID. The limit defaults to 50 and is capped at 200. When this build does not include a compatible Huly external-message SDK/model for the requested provider, returns supported=false, an unsupportedReason, and an empty messages array; it never sends, replies, deletes, mutates, or returns fake messages. |
 | `send_channel_message` | Send a message to a Huly channel. Message body supports markdown formatting. |
 | `update_channel_message` | Update a channel message. Only the body can be modified. |
 | `delete_channel_message` | Permanently delete a channel message. This action cannot be undone. |
@@ -739,6 +740,9 @@ SDK upgrade revisit:
 | `add_space_members` | Idempotently add members to an existing Huly space. Members accept account UUID, exact email, or exact person display name and resolve to Huly account UUIDs before replacing the full members array. |
 | `remove_space_members` | Idempotently remove members from an existing Huly space. Members accept account UUID, exact email, or exact person display name and resolve to Huly account UUIDs before replacing the full members array. |
 | `set_space_owners` | Replace owners on an existing Huly space. Owners accept account UUID, exact email, or exact person display name. By default, owners are also ensured in members. |
+| `set_space_role_members` | Replace members assigned to one role on a typed Huly space while preserving all other role assignments. Role accepts a raw role _id or exact role name from the space's SpaceType. Members accept account UUID, exact email, or exact person display name; pass members=[] to clear this role. |
+| `add_space_role_members` | Idempotently add members to one role on a typed Huly space while preserving all other role assignments. Role accepts a raw role _id or exact role name from the space's SpaceType. Members accept account UUID, exact email, or exact person display name. |
+| `remove_space_role_members` | Idempotently remove members from one role on a typed Huly space while preserving all other role assignments. Role accepts a raw role _id or exact role name from the space's SpaceType. Members accept account UUID, exact email, or exact person display name. |
 
 ### Tag-Categories
 

package/dist/index.cjs

@@ -154570,6 +154570,10 @@ var AmbiguousSpaceTypeMatchSchema = Schema_exports.Struct({
   name: NonEmptyString2,
   targetClass: ObjectClassName
 });
+var AmbiguousSpaceRoleMatchSchema = Schema_exports.Struct({
+  id: RoleId,
+  name: NonEmptyString2
+});
 var SpaceNotFoundError = class extends Schema_exports.TaggedError()(
   "SpaceNotFoundError",
   {
@@ -154614,6 +154618,54 @@ var SpaceTypeIdentifierAmbiguousError = class extends Schema_exports.TaggedError
     return `Space type '${this.identifier}' is ambiguous; use a space type id. Matches: ${details}`;
   }
 };
+var SpaceNotTypedError = class extends Schema_exports.TaggedError()(
+  "SpaceNotTypedError",
+  {
+    id: SpaceId,
+    name: NonEmptyString2
+  }
+) {
+  get message() {
+    return `Space '${this.name}' (${this.id}) is not typed; role members can only be changed on spaces with a SpaceType`;
+  }
+};
+var SpaceRoleNotFoundError = class extends Schema_exports.TaggedError()(
+  "SpaceRoleNotFoundError",
+  {
+    identifier: NonEmptyString2,
+    spaceType: SpaceTypeId
+  }
+) {
+  get message() {
+    return `Role '${this.identifier}' not found in space type '${this.spaceType}'`;
+  }
+};
+var SpaceRoleIdentifierAmbiguousError = class extends Schema_exports.TaggedError()(
+  "SpaceRoleIdentifierAmbiguousError",
+  {
+    identifier: NonEmptyString2,
+    spaceType: SpaceTypeId,
+    matches: Schema_exports.Array(AmbiguousSpaceRoleMatchSchema).pipe(Schema_exports.minItems(MIN_AMBIGUOUS_SPACE_MATCHES))
+  }
+) {
+  get message() {
+    const details = this.matches.map((match16) => `${match16.id} (${match16.name})`).join(", ");
+    return `Role '${this.identifier}' is ambiguous in space type '${this.spaceType}'; use a role id. Matches: ${details}`;
+  }
+};
+var SpaceRoleAssignmentsMalformedError = class extends Schema_exports.TaggedError()(
+  "SpaceRoleAssignmentsMalformedError",
+  {
+    space: SpaceId,
+    spaceType: SpaceTypeId,
+    targetClass: ObjectClassName,
+    reason: NonEmptyString2
+  }
+) {
+  get message() {
+    return `Role assignments for space '${this.space}' and space type '${this.spaceType}' are malformed at '${this.targetClass}': ${this.reason}. Refusing to write role members to avoid access-control data loss.`;
+  }
+};
 
 // src/huly/errors-test-management.ts
 var TestProjectNotFoundError = class extends Schema_exports.TaggedError()(
@@ -154890,6 +154942,10 @@ var HulyDomainError = Schema_exports.Union(
   HulyClassNotFoundError,
   SpaceNotFoundError,
   SpaceIdentifierAmbiguousError,
+  SpaceNotTypedError,
+  SpaceRoleNotFoundError,
+  SpaceRoleIdentifierAmbiguousError,
+  SpaceRoleAssignmentsMalformedError,
   SpaceTypeNotFoundError,
   SpaceTypeIdentifierAmbiguousError,
   TodoNotFoundError,
@@ -155260,6 +155316,10 @@ var HulyClient = class _HulyClient extends Context_exports.Tag("@hulymcp/HulyCli
           (client2) => client2.findOne(_class, query, options),
           "findOne failed"
         ),
+        findAllInModel: (_class, query, options) => withClient(
+          (client2) => Promise.resolve(client2.getModel().findAllSync(_class, query, options)),
+          "findAllInModel failed"
+        ),
         createDoc: (_class, space, attributes, id) => withClient(
           (client2) => client2.createDoc(_class, space, attributes, id),
           "createDoc failed"
@@ -155341,6 +155401,7 @@ var HulyClient = class _HulyClient extends Context_exports.Tag("@hulymcp/HulyCli
       markupUrlConfig: testMarkupUrlConfig,
       workbenchUrlConfig: testWorkbenchUrlConfig,
       findAll: noopFindAll,
+      findAllInModel: noopFindAll,
       findOne: noopFindOne,
       createDoc: notImplemented("createDoc"),
       updateDoc: notImplemented("updateDoc"),
@@ -155418,6 +155479,7 @@ var import_api_client3 = __toESM(require_lib20(), 1);
 // src/huly/operations/sdk-boundary.ts
 var toRef = (id) => id;
 var toClassRef = (id) => id;
+var toMixinRef = (id) => id;
 var toAccountUuid = (uuid5) => uuid5;
 var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var validatePersonUuid = (uuid5) => {
@@ -165740,11 +165802,14 @@ var McpErrorCode = {
   InternalError: -32603,
   ResourceNotFound: -32002
 };
-var createErrorResponse = (text, errorCode, errorTag) => ({
-  content: [{ type: "text", text }],
-  isError: true,
-  _meta: { errorCode, errorTag }
-});
+var createErrorResponse = (text, errorCode, errorTag, warnings = []) => {
+  const warningContent = warnings.length > 0 ? [{ type: "text", text: encodeJsonText({ warnings }) }] : [];
+  return {
+    content: [{ type: "text", text }, ...warningContent],
+    isError: true,
+    _meta: { errorCode, errorTag }
+  };
+};
 var INVALID_PARAMS_TAGS = /* @__PURE__ */ new Set([
   "IssueNotFoundError",
   "ProjectNotFoundError",
@@ -165835,6 +165900,9 @@ var INVALID_PARAMS_TAGS = /* @__PURE__ */ new Set([
   "GenericObjectNotFoundError",
   "SpaceNotFoundError",
   "SpaceIdentifierAmbiguousError",
+  "SpaceNotTypedError",
+  "SpaceRoleNotFoundError",
+  "SpaceRoleIdentifierAmbiguousError",
   "SpaceTypeNotFoundError",
   "SpaceTypeIdentifierAmbiguousError",
   "DriveNotFoundError",
@@ -165857,13 +165925,13 @@ var INTERNAL_ERROR_PREFIX = {
   HulyConnectionError: "Connection error",
   HulyAuthError: "Authentication error"
 };
-var mapDomainErrorToMcp = (error2) => {
+var mapDomainErrorToMcp = (error2, warnings = []) => {
   if (INVALID_PARAMS_TAGS.has(error2._tag)) {
-    return createErrorResponse(error2.message, McpErrorCode.InvalidParams);
+    return createErrorResponse(error2.message, McpErrorCode.InvalidParams, void 0, warnings);
   }
   const prefix = INTERNAL_ERROR_PREFIX[error2._tag];
   const message = prefix !== void 0 ? `${prefix}: ${error2.message}` : error2.message;
-  return createErrorResponse(message, McpErrorCode.InternalError, error2._tag);
+  return createErrorResponse(message, McpErrorCode.InternalError, error2._tag, warnings);
 };
 var formatParseError = (error2) => {
   const issues = ParseResult_exports.ArrayFormatter.formatErrorSync(error2);
@@ -165884,34 +165952,44 @@ var mapParseCauseToMcp = (cause3, toolName) => {
   }
   return createErrorResponse("An unexpected error occurred", McpErrorCode.InternalError);
 };
-var mapDomainCauseToMcp = (cause3) => {
+var mapDomainCauseToMcp = (cause3, warnings = []) => {
   if (Cause_exports.isFailType(cause3)) {
-    return mapDomainErrorToMcp(cause3.error);
+    return mapDomainErrorToMcp(cause3.error, warnings);
   }
   if (Cause_exports.isDieType(cause3)) {
-    return createErrorResponse("An unexpected error occurred", McpErrorCode.InternalError, "UnexpectedError");
+    return createErrorResponse("An unexpected error occurred", McpErrorCode.InternalError, "UnexpectedError", warnings);
   }
   const failures3 = Chunk_exports.toArray(Cause_exports.failures(cause3));
   if (failures3.length > 0) {
-    return mapDomainErrorToMcp(failures3[0]);
+    return mapDomainErrorToMcp(failures3[0], warnings);
   }
-  return createErrorResponse("An unexpected error occurred", McpErrorCode.InternalError);
+  return createErrorResponse("An unexpected error occurred", McpErrorCode.InternalError, void 0, warnings);
 };
 var encodeJsonText = (value3) => {
   const text = JSON.stringify(value3);
   return typeof text === "string" ? text : "null";
 };
-var createSuccessResponse = (result) => ({
-  content: [{ type: "text", text: encodeJsonText(result) }],
-  structuredContent: {
+var createSuccessResponse = (result, warnings = []) => ({
+  content: [
+    { type: "text", text: encodeJsonText(result) },
+    ...warnings.length > 0 ? [{ type: "text", text: encodeJsonText({ warnings }) }] : []
+  ],
+  structuredContent: warnings.length > 0 ? {
+    result,
+    warnings
+  } : {
     result
   }
 });
 var createUnknownToolError = (toolName) => createErrorResponse(`Unknown tool: ${toolName}`, McpErrorCode.InvalidParams, "UnknownTool");
 var createInvalidParamsError = (message, errorTag) => createErrorResponse(message, McpErrorCode.InvalidParams, errorTag);
-var toMcpResponse = (response) => {
-  const { _meta: _, ...wire } = response;
-  return wire;
+var toMcpResponse = (response) => response.isError === true ? {
+  content: response.content,
+  isError: true
+} : {
+  content: response.content,
+  ...response.structuredContent === void 0 ? {} : { structuredContent: response.structuredContent },
+  ...response.isError === void 0 ? {} : { isError: response.isError }
 };
 
 // src/mcp/http-2026-dispatcher.ts
@@ -166468,6 +166546,28 @@ var StdioServerTransport = class {
   }
 };
 
+// src/domain/schemas/tool-warnings.ts
+var ToolWarningCodeSchema = Schema_exports.Literal(
+  "status_metadata_unresolved",
+  "space_role_assignments_degraded"
+).annotations({
+  identifier: "ToolWarningCode",
+  title: "ToolWarningCode",
+  description: "Machine-readable code for an agent-visible MCP tool warning."
+});
+var StatusMetadataUnresolvedWarningCode = ToolWarningCodeSchema.literals[0];
+var SpaceRoleAssignmentsDegradedWarningCode = ToolWarningCodeSchema.literals[1];
+var ToolWarningSchema = Schema_exports.Struct({
+  code: ToolWarningCodeSchema,
+  message: Schema_exports.Trim.pipe(Schema_exports.nonEmptyString()).annotations({
+    description: "LLM-facing explanation of what part of the returned tool payload is degraded and how the agent should interpret it."
+  })
+}).annotations({
+  identifier: "ToolWarning",
+  title: "ToolWarning",
+  description: "Warning surfaced to an agent when a tool result is intentionally degraded instead of failing."
+});
+
 // src/domain/schemas/recurrence-primitives.ts
 var MAX_ZERO_BASED_MONTH_INDEX = 11;
 var MAX_MONTH_DAY = 31;
@@ -166518,9 +166618,13 @@ var clearableText = (description) => Schema_exports.NullOr(Schema_exports.String
 var limitDescription = (subject) => `Maximum ${subject} to return (default: ${DEFAULT_LIMIT}).`;
 var SpacePermissionScopeSchema = Schema_exports.Literal("space", "workspace");
 var SpaceMemberIdentifier = NonEmptyString2.pipe(Schema_exports.brand("SpaceMemberIdentifier"));
+var SpaceRoleIdentifier = NonEmptyString2.pipe(Schema_exports.brand("SpaceRoleIdentifier"));
 var SpaceMemberIdentifierSchema = SpaceMemberIdentifier.annotations({
   description: "Workspace member to resolve. Accepts a Huly account UUID directly, an exact email address, or an exact person display name."
 });
+var SpaceRoleIdentifierSchema = SpaceRoleIdentifier.annotations({
+  description: "Role to resolve within the space's SpaceType. Accepts a raw Huly role _id or an exact role name from get_space_type."
+});
 var SpaceRoleAssignmentSchema = Schema_exports.Struct({
   roleId: RoleId,
   members: Schema_exports.Array(AccountUuid)
@@ -166695,6 +166799,28 @@ var SetSpaceOwnersParamsSchema = Schema_exports.Struct({
     description: `Also add each owner to members. Defaults to ${DEFAULT_SPACE_OWNER_ENSURE_MEMBERS}.`
   }))
 });
+var SpaceRoleMemberMutationFields = {
+  space: SpaceIdentifier.annotations({
+    description: "Typed space _id or exact space name whose role assignment should change. The space must have a SpaceType."
+  }),
+  class: Schema_exports.optional(SpaceClassFilter.annotations({
+    description: "Optional raw Huly space class ID used to disambiguate exact-name lookup."
+  })),
+  type: Schema_exports.optional(SpaceTypeId.annotations({
+    description: "Optional raw Huly SpaceType _id used to disambiguate exact-name lookup."
+  })),
+  role: SpaceRoleIdentifierSchema,
+  members: Schema_exports.Array(SpaceMemberIdentifierSchema).pipe(Schema_exports.minItems(1)).annotations({
+    description: "Members to add or remove from this role. Each entry may be an account UUID, exact email address, or exact person name."
+  })
+};
+var SpaceRoleMemberMutationParamsSchema = Schema_exports.Struct(SpaceRoleMemberMutationFields);
+var SetSpaceRoleMembersParamsSchema = Schema_exports.Struct({
+  ...SpaceRoleMemberMutationFields,
+  members: Schema_exports.Array(SpaceMemberIdentifierSchema).annotations({
+    description: "Replacement member list for this role only. Each entry may be an account UUID, exact email address, or exact person name. Pass [] to clear this role."
+  })
+});
 var listSpacesParamsJsonSchema = JSONSchema_exports.make(ListSpacesParamsSchema);
 var getSpaceParamsJsonSchema = JSONSchema_exports.make(GetSpaceParamsSchema);
 var listSpaceTypesParamsJsonSchema = JSONSchema_exports.make(ListSpaceTypesParamsSchema);
@@ -166706,6 +166832,8 @@ var updateSpaceParamsJsonSchema = withAtLeastOneRequired(
 );
 var spaceMemberMutationParamsJsonSchema = JSONSchema_exports.make(SpaceMemberMutationParamsSchema);
 var setSpaceOwnersParamsJsonSchema = JSONSchema_exports.make(SetSpaceOwnersParamsSchema);
+var spaceRoleMemberMutationParamsJsonSchema = JSONSchema_exports.make(SpaceRoleMemberMutationParamsSchema);
+var setSpaceRoleMembersParamsJsonSchema = JSONSchema_exports.make(SetSpaceRoleMembersParamsSchema);
 var parseListSpacesParams = Schema_exports.decodeUnknown(ListSpacesParamsSchema);
 var parseGetSpaceParams = Schema_exports.decodeUnknown(GetSpaceParamsSchema);
 var parseListSpaceTypesParams = Schema_exports.decodeUnknown(ListSpaceTypesParamsSchema);
@@ -166714,6 +166842,8 @@ var parseListSpacePermissionsParams = Schema_exports.decodeUnknown(ListSpacePerm
 var parseUpdateSpaceParams = Schema_exports.decodeUnknown(UpdateSpaceParamsSchema);
 var parseSpaceMemberMutationParams = Schema_exports.decodeUnknown(SpaceMemberMutationParamsSchema);
 var parseSetSpaceOwnersParams = Schema_exports.decodeUnknown(SetSpaceOwnersParamsSchema);
+var parseSpaceRoleMemberMutationParams = Schema_exports.decodeUnknown(SpaceRoleMemberMutationParamsSchema);
+var parseSetSpaceRoleMembersParams = Schema_exports.decodeUnknown(SetSpaceRoleMembersParamsSchema);
 
 // src/domain/schemas/sdk-discovery.ts
 var import_core10 = __toESM(require_lib4(), 1);
@@ -167252,6 +167382,7 @@ var ProjectTypeDetailSchema = Schema_exports.Struct({
   descriptor: NonEmptyString2,
   classic: Schema_exports.Boolean,
   isDefaultClassic: Schema_exports.Boolean,
+  statusCount: Count,
   taskTypes: Schema_exports.Array(TaskTypeSummarySchema),
   statuses: Schema_exports.Array(IssueStatusSummarySchema),
   statusCategories: Schema_exports.Array(StatusCategorySummarySchema),
@@ -170099,6 +170230,91 @@ var parseUpdatePersonParams = Schema_exports.decodeUnknown(UpdatePersonParamsSch
 var parseDeletePersonParams = Schema_exports.decodeUnknown(DeletePersonParamsSchema);
 var parseListEmployeesParams = Schema_exports.decodeUnknown(ListEmployeesParamsSchema);
 
+// src/domain/schemas/external-channel-messages.ts
+var ExternalChannelMessageProviderValues = ["gmail", "telegram"];
+var ExternalChannelMessageProviderSchema = Schema_exports.Literal(...ExternalChannelMessageProviderValues);
+var DEFAULT_EXTERNAL_CHANNEL_MESSAGE_LIMIT = DEFAULT_LIMIT;
+var ListExternalChannelMessagesParamsSchema = Schema_exports.Struct({
+  provider: ExternalChannelMessageProviderSchema.annotations({
+    description: "External provider to read from. Supported locator values are validated for gmail and telegram; providers without a compatible installed Huly message SDK return structured unsupported results instead of fake data."
+  }),
+  channel: ChannelIdentifier.annotations({
+    description: "External channel name or Huly channel ID locator, such as a Gmail label/inbox name or Telegram chat name/id."
+  }),
+  limit: Schema_exports.optional(LimitParam.annotations({
+    description: `Maximum number of external messages to return (default: ${DEFAULT_EXTERNAL_CHANNEL_MESSAGE_LIMIT}, max: 200).`
+  }))
+}).annotations({
+  title: "ListExternalChannelMessagesParams",
+  description: "Parameters for listing read-only Gmail or Telegram external channel messages."
+});
+var ExternalChannelMessageId = NonEmptyString2.pipe(Schema_exports.brand("ExternalChannelMessageId")).annotations({
+  identifier: "ExternalChannelMessageId",
+  title: "ExternalChannelMessageId",
+  description: "Opaque external provider message ID."
+});
+var ExternalChannelMessageSubject = NonEmptyString2.pipe(
+  Schema_exports.brand("ExternalChannelMessageSubject")
+).annotations({
+  identifier: "ExternalChannelMessageSubject",
+  title: "ExternalChannelMessageSubject",
+  description: "Non-empty external message subject. Omit the field when the provider has no subject value."
+});
+var ExternalChannelMessageSender = NonEmptyString2.pipe(Schema_exports.brand("ExternalChannelMessageSender")).annotations({
+  identifier: "ExternalChannelMessageSender",
+  title: "ExternalChannelMessageSender",
+  description: "Non-empty normalized external message sender label or address."
+});
+var ExternalChannelMessageSenderId = NonEmptyString2.pipe(Schema_exports.brand("ExternalChannelMessageSenderId")).annotations({
+  identifier: "ExternalChannelMessageSenderId",
+  title: "ExternalChannelMessageSenderId",
+  description: "Non-empty opaque external provider sender ID."
+});
+var ExternalChannelMessageSummarySchema = Schema_exports.Struct({
+  id: ExternalChannelMessageId,
+  subject: Schema_exports.optional(ExternalChannelMessageSubject),
+  bodyPreview: NonEmptyString2,
+  sender: Schema_exports.optional(ExternalChannelMessageSender),
+  senderId: Schema_exports.optional(ExternalChannelMessageSenderId),
+  createdOn: Schema_exports.optional(Timestamp),
+  modifiedOn: Schema_exports.optional(Timestamp),
+  url: Schema_exports.optional(UrlString)
+}).annotations({
+  title: "ExternalChannelMessageSummary",
+  description: "Normalized read-only summary of one external Gmail or Telegram message."
+});
+var ListExternalChannelMessagesSupportedResultSchema = Schema_exports.Struct({
+  supported: Schema_exports.Literal(true),
+  provider: ExternalChannelMessageProviderSchema,
+  channel: ChannelIdentifier,
+  limit: LimitParam,
+  messages: Schema_exports.Array(ExternalChannelMessageSummarySchema)
+}).annotations({
+  title: "ListExternalChannelMessagesSupportedResult",
+  description: "External channel messages returned from a compatible installed Huly provider SDK/model."
+});
+var ListExternalChannelMessagesUnsupportedResultSchema = Schema_exports.Struct({
+  supported: Schema_exports.Literal(false),
+  provider: ExternalChannelMessageProviderSchema,
+  channel: ChannelIdentifier,
+  limit: LimitParam,
+  unsupportedReason: NonEmptyString2,
+  messages: Schema_exports.Tuple()
+}).annotations({
+  title: "ListExternalChannelMessagesUnsupportedResult",
+  description: "Explicit no-fake-data result when the requested external provider cannot be read in this build."
+});
+var ListExternalChannelMessagesResultSchema = Schema_exports.Union(
+  ListExternalChannelMessagesSupportedResultSchema,
+  ListExternalChannelMessagesUnsupportedResultSchema
+).annotations({
+  title: "ListExternalChannelMessagesResult",
+  description: "Read-only external channel message listing result."
+});
+var listExternalChannelMessagesParamsJsonSchema = JSONSchema_exports.make(ListExternalChannelMessagesParamsSchema);
+var parseListExternalChannelMessagesParams = Schema_exports.decodeUnknown(ListExternalChannelMessagesParamsSchema);
+var encodeListExternalChannelMessagesResult = Schema_exports.encodeSync(ListExternalChannelMessagesResultSchema);
+
 // src/domain/schemas/channels.ts
 var ListChannelsParamsBase = Schema_exports.Struct({
   nameSearch: Schema_exports.optional(Schema_exports.String.annotations({
@@ -174502,15 +174718,52 @@ var parseUpdateDriveFileCommentParams = Schema_exports.decodeUnknown(UpdateDrive
 var parseDeleteDriveFileCommentParams = Schema_exports.decodeUnknown(DeleteDriveFileCommentParamsSchema);
 var parseListDriveFileActivityParams = Schema_exports.decodeUnknown(ListDriveFileActivityParamsSchema);
 
+// src/huly/diagnostics.ts
+var Diagnostics = class extends Context_exports.Tag("@hulymcp/Diagnostics")() {
+};
+var warningLogText = (warning) => `Agent-visible tool warning [${warning.code}]: ${warning.message}`;
+var makeDiagnosticsScope = Effect_exports.gen(function* () {
+  const warningsRef = yield* Ref_exports.make([]);
+  return {
+    service: {
+      warnAgent: (warning) => Ref_exports.update(warningsRef, (warnings) => [...warnings, warning]).pipe(
+        Effect_exports.zipRight(Effect_exports.logWarning(warningLogText(warning)))
+      ),
+      trail: (message) => Effect_exports.logInfo(`Diagnostic trail: ${message}`)
+    },
+    drainWarnings: Ref_exports.get(warningsRef)
+  };
+});
+
 // src/version.ts
-var VERSION = true ? "0.30.1" : "0.0.0-dev";
+var VERSION = true ? "0.31.1" : "0.0.0-dev";
 
 // src/mcp/tool-output-schema.ts
+var toolWarningCodeEnum = [...ToolWarningCodeSchema.literals];
 var defaultToolOutputSchema = {
   type: "object",
   properties: {
     result: {
       description: "The successful tool result. The same value is also serialized as JSON in the text content for clients that do not read structuredContent."
+    },
+    warnings: {
+      type: "array",
+      description: "Optional agent-visible warnings about degraded result fidelity. Omitted when the server returned the documented happy-path payload.",
+      items: {
+        type: "object",
+        properties: {
+          code: {
+            type: "string",
+            enum: toolWarningCodeEnum
+          },
+          message: {
+            type: "string",
+            minLength: 1
+          }
+        },
+        required: ["code", "message"],
+        additionalProperties: false
+      }
     }
   },
   required: ["result"]
@@ -174983,6 +175236,93 @@ var removeAccountUuids = (current, removals) => {
 var arraysEqual = (left3, right3) => left3.length === right3.length && left3.every((value3, index) => value3 === right3[index]);
 var optionalString = (value3) => value3 === void 0 || value3 === "" ? void 0 : value3;
 var optionalObjectClassName = (value3) => value3 === void 0 || value3 === "" ? void 0 : ObjectClassName.make(value3);
+var RoleAssignmentStorageSchema = Schema_exports.Record({ key: Schema_exports.String, value: Schema_exports.Array(AccountUuid) });
+var isRecordObject = (value3) => typeof value3 === "object" && value3 !== null && !Array.isArray(value3);
+var validStoredAccountUuid = (value3) => {
+  const decoded = Schema_exports.decodeUnknownEither(AccountUuid)(value3);
+  return decoded._tag === "Right" ? toAccountUuid(NonEmptyString2.make(decoded.right)) : void 0;
+};
+var parsedSpaceRoleAssignmentEntry = (roleId, members) => ({
+  _tag: "entry",
+  entry: [
+    toRef(roleId),
+    sortStrings(members).map(toAccountUuid)
+  ]
+});
+var spaceRoleAssignmentSource = (space, spaceType) => Object.prototype.hasOwnProperty.call(space, spaceType.targetClass) ? { present: true, value: Object.entries(space).find(([key]) => key === spaceType.targetClass)?.[1] } : { present: false, value: void 0 };
+var roleAssignmentsMalformedError = (space, spaceType, reason) => new SpaceRoleAssignmentsMalformedError({
+  space: SpaceId.make(space._id),
+  spaceType: SpaceTypeId.make(spaceType._id),
+  targetClass: ObjectClassName.make(spaceType.targetClass),
+  reason: NonEmptyString2.make(reason)
+});
+var readSpaceRoleAssignmentEntries = (space, spaceType, validRoleIds) => {
+  const source = spaceRoleAssignmentSource(space, spaceType);
+  if (!source.present) return { entries: [], degradationReasons: [] };
+  if (!isRecordObject(source.value)) {
+    return {
+      entries: [],
+      degradationReasons: [`role assignment mixin ${spaceType.targetClass} is not an object`]
+    };
+  }
+  const parsed = Object.entries(source.value).flatMap(([roleId, members]) => {
+    if (!validRoleIds.has(toRef(roleId))) {
+      return [{
+        _tag: "dropped",
+        reason: `role assignment '${roleId}' is not defined on space type ${spaceType._id}`
+      }];
+    }
+    if (!Array.isArray(members)) {
+      return [{ _tag: "dropped", reason: `role assignment '${roleId}' members are not an array` }];
+    }
+    const accountUuids = members.flatMap((member) => {
+      const accountUuid = validStoredAccountUuid(member);
+      return accountUuid === void 0 ? [] : [accountUuid];
+    });
+    const invalidMemberCount = members.length - accountUuids.length;
+    return [
+      ...invalidMemberCount > 0 ? [{
+        _tag: "dropped",
+        reason: `role assignment '${roleId}' has ${invalidMemberCount} malformed account UUID value(s)`
+      }] : [],
+      parsedSpaceRoleAssignmentEntry(roleId, accountUuids)
+    ];
+  });
+  return {
+    entries: parsed.flatMap((item) => item._tag === "entry" ? [item.entry] : []),
+    degradationReasons: parsed.flatMap((item) => item._tag === "dropped" ? [item.reason] : [])
+  };
+};
+var spaceRoleAssignmentEntries = (space, spaceType, validRoleIds) => readSpaceRoleAssignmentEntries(space, spaceType, validRoleIds).entries;
+var hasSpaceRoleAssignmentMixin = (space, spaceType) => spaceRoleAssignmentSource(space, spaceType).present;
+var strictSpaceRoleAssignments = (space, spaceType, validRoleIds) => Effect_exports.gen(function* () {
+  const source = spaceRoleAssignmentSource(space, spaceType);
+  if (!source.present) return {};
+  const decoded = Schema_exports.decodeUnknownEither(RoleAssignmentStorageSchema)(source.value);
+  if (decoded._tag === "Left") {
+    return yield* roleAssignmentsMalformedError(
+      space,
+      spaceType,
+      `expected an object whose keys are role ids and values are arrays of account UUIDs`
+    );
+  }
+  const unknownRoleIds = Object.keys(decoded.right).filter((roleId) => !validRoleIds.has(toRef(roleId)));
+  if (unknownRoleIds.length > 0) {
+    return yield* roleAssignmentsMalformedError(
+      space,
+      spaceType,
+      `unknown role assignment key(s): ${unknownRoleIds.join(", ")}`
+    );
+  }
+  return Object.fromEntries(
+    Object.entries(decoded.right).map(([roleId, members]) => [
+      toRef(roleId),
+      members.map((member) => toAccountUuid(NonEmptyString2.make(member)))
+    ])
+  );
+});
+var roleAssignmentDegradationMessage = (reasons) => `Some typed-space role assignment data was omitted because existing Huly storage is malformed: ${reasons.join("; ")}. Read results include only valid role assignments; role-member write tools will refuse to modify this space until the stored role assignment data is repaired.`;
+var spaceRoleAssignmentsMixin = (spaceType) => toMixinRef(spaceType.targetClass);
 var applySpaceFilters = (query, filters) => {
   const next4 = { ...query };
   if (!filters.includeArchived) {
@@ -176182,7 +176522,7 @@ var findProject = (projectIdentifier) => Effect_exports.gen(function* () {
   );
   return { client, project: project3 };
 });
-var statusCategoryValueFromRef = (category) => category === void 0 ? "unknown" : StatusCategoryEntries.find((entry) => entry.ref === category)?.key ?? "unknown";
+var statusCategoryValueFromRef = (category) => category === void 0 ? UnknownStatusCategoryValue : StatusCategoryEntries.find((entry) => entry.ref === category)?.key ?? UnknownStatusCategoryValue;
 var workflowStatusFromDoc = (doc) => {
   return {
     _id: doc._id,
@@ -176195,7 +176535,7 @@ var workflowStatusFromRef = (statusRef) => {
   return {
     _id: statusRef,
     name,
-    category: "unknown"
+    category: UnknownStatusCategoryValue
   };
 };
 var uniqueStatusRefs = (refs) => refs.reduce(
@@ -176207,6 +176547,51 @@ var uniqueStatusDocs = (statuses) => Array.from(statuses).reduce(
   []
 );
 var uniqueProjectTypeStatusRefs = (statuses) => uniqueStatusRefs(statuses.map((status) => status._id));
+var missingStatusRefs = (statusRefs, statusDocs) => statusRefs.filter((statusRef) => !statusDocs.some((statusDoc) => statusDoc._id === statusRef));
+var resolveByStatusRef = (statusRefs, statusDocs, fromDoc, fromRef) => {
+  const statusDocsById = new Map(statusDocs.map((statusDoc) => [statusDoc._id, statusDoc]));
+  return statusRefs.map((statusRef) => {
+    const statusDoc = statusDocsById.get(statusRef);
+    return statusDoc === void 0 ? fromRef(statusRef) : fromDoc(statusDoc);
+  });
+};
+var workflowStatusesFromDocsOrRefs = (statusRefs, statusDocs) => resolveByStatusRef(statusRefs, statusDocs, workflowStatusFromDoc, workflowStatusFromRef);
+var findStatusDocs = (client, statusRefs) => Effect_exports.gen(function* () {
+  const diagnostics = yield* Diagnostics;
+  const remoteResult = yield* Effect_exports.either(
+    client.findAll(
+      core.class.Status,
+      hulyQuery({ _id: { $in: [...statusRefs] } })
+    )
+  );
+  const remoteDocs = remoteResult._tag === "Right" ? uniqueStatusDocs(remoteResult.right) : [];
+  const unresolvedRefs = missingStatusRefs(statusRefs, remoteDocs);
+  if (unresolvedRefs.length === 0) {
+    return remoteDocs;
+  }
+  const modelResult = yield* Effect_exports.either(
+    client.findAllInModel(
+      core.class.Status,
+      hulyQuery({ _id: { $in: unresolvedRefs } })
+    )
+  );
+  const modelDocs = modelResult._tag === "Right" ? uniqueStatusDocs(modelResult.right) : [];
+  const combinedDocs = uniqueStatusDocs([...remoteDocs, ...modelDocs]);
+  const stillUnresolvedRefs = missingStatusRefs(statusRefs, combinedDocs);
+  if (stillUnresolvedRefs.length > 0) {
+    const remoteError = remoteResult._tag === "Left" ? ` Remote error: ${remoteResult.left.message}` : "";
+    const modelError = modelResult._tag === "Left" ? ` Model error: ${modelResult.left.message}` : "";
+    yield* diagnostics.warnAgent({
+      code: StatusMetadataUnresolvedWarningCode,
+      message: `Huly did not return metadata for ${stillUnresolvedRefs.length} workflow status ref(s). The tool result uses ref-derived status names and category "${UnknownStatusCategoryValue}" for those statuses; do not infer completion or cancellation semantics from those fallback names.${remoteError}${modelError}`
+    });
+  } else if (remoteResult._tag === "Left") {
+    yield* diagnostics.trail(
+      `Server status metadata lookup failed, but the local Huly model resolved all requested workflow statuses. Remote error: ${remoteResult.left.message}`
+    );
+  }
+  return combinedDocs;
+});
 var findProjectWithStatuses = (projectIdentifier) => Effect_exports.gen(function* () {
   const client = yield* HulyClient;
   const project3 = yield* findOneOrFail(
@@ -176222,19 +176607,8 @@ var findProjectWithStatuses = (projectIdentifier) => Effect_exports.gen(function
     if (statusRefs.length === 0) {
       return [];
     }
-    const statusDocsResult = yield* Effect_exports.either(
-      client.findAll(
-        core.class.Status,
-        hulyQuery({ _id: { $in: statusRefs } })
-      )
-    );
-    if (statusDocsResult._tag === "Right") {
-      return uniqueStatusDocs(statusDocsResult.right).map(workflowStatusFromDoc);
-    }
-    yield* Effect_exports.logWarning(
-      `Status query failed for project ${projectIdentifier}, using fallback. statusCategory filtering is unavailable until Huly returns status metadata. Error: ${statusDocsResult.left.message}`
-    );
-    return statusRefs.map(workflowStatusFromRef);
+    const statusDocs = yield* findStatusDocs(client, statusRefs);
+    return workflowStatusesFromDocsOrRefs(statusRefs, statusDocs);
   }) : [];
   const defaultStatusId = project3.defaultIssueStatus || statuses[0]?._id;
   return { client, defaultStatusId, project: project3, projectType, statuses };
@@ -176598,19 +176972,27 @@ var createHandler = (toolName, provide4, parse5, operation, encode8) => async (a
   if (Exit_exports.isFailure(parseResult)) {
     return mapParseCauseToMcp(parseResult.cause, toolName);
   }
-  const provided = provide4({ hulyClient, storageClient, workspaceClient })(operation(parseResult.value));
+  const diagnosticsScope = await Effect_exports.runPromise(makeDiagnosticsScope);
+  const provided = provide4({
+    hulyClient,
+    storageClient,
+    workspaceClient
+  })(operation(parseResult.value));
   if (Either_exports.isLeft(provided)) {
     return provided.left;
   }
-  const operationResult = await Effect_exports.runPromiseExit(provided.right);
+  const operationResult = await Effect_exports.runPromiseExit(
+    provided.right.pipe(Effect_exports.provideService(Diagnostics, diagnosticsScope.service))
+  );
+  const warnings = await Effect_exports.runPromise(diagnosticsScope.drainWarnings);
   if (Exit_exports.isFailure(operationResult)) {
-    return mapDomainCauseToMcp(operationResult.cause);
+    return mapDomainCauseToMcp(operationResult.cause, warnings);
   }
   try {
     const output = encode8 !== void 0 ? encode8(operationResult.value) : operationResult.value;
-    return createSuccessResponse(output);
+    return createSuccessResponse(output, warnings);
   } catch {
-    return mapDomainErrorToMcp(new HulyError({ message: `Tool ${toolName} produced invalid output` }));
+    return mapDomainErrorToMcp(new HulyError({ message: `Tool ${toolName} produced invalid output` }), warnings);
   }
 };
 var createToolHandler = (toolName, parse5, operation) => createHandler(toolName, provideHulyClient, parse5, operation);
@@ -178722,7 +179104,7 @@ var contactCoveredRationale = "Current contacts tools expose person, organizatio
 var cardCoveredRationale = "Current card tools cover card spaces, master tags, and card CRUD.";
 var chunterCoveredRationale = "Current channel and direct-message tools cover channels, channel messages, one-to-one DM listing, and thread replies.";
 var coreCoveredRationale = "Existing tools expose user statuses, full-text search, blobs through storage/download flows, generic association/relation discovery/mutation helpers, class/interface/mixin, attribute, enum, plugin configuration, domain index configuration, sequence, and space type capability discovery.";
-var coreGapRationale = "Remaining core write-side configuration, role assignment writes, role/permission definition writes, generic space creation, class collaborator metadata, statuses, and write-side model management are represented as matrix gaps. Generic space discovery, space type/permission reads, safe existing-space metadata updates, member mutations, owner replacement, object collaborators, read-only plugin configuration, domain index configuration, and sequence discovery are covered.";
+var coreGapRationale = "Remaining core write-side configuration, role/permission definition writes, generic space creation, class collaborator metadata, statuses, and write-side model management are represented as matrix gaps. Generic space discovery, space type/permission reads, safe existing-space metadata updates, member mutations, owner replacement, typed-space role member mutations, object collaborators, read-only plugin configuration, domain index configuration, and sequence discovery are covered.";
 var coreNotMcpFacingRationale = "Core primitive model infrastructure, transaction classes, type wrappers, and versioning internals are not LLM-facing product resources by themselves.";
 var routingRow = (classId, packageName, exportName, hint) => ({
   classId: ObjectClassName.make(classId),
@@ -179513,6 +179895,19 @@ var createDirectMessage = (params) => Effect_exports.gen(function* () {
   return { id: ChannelId.make(dmId), created: true };
 });
 
+// src/huly/operations/external-channel-messages.ts
+var EXTERNAL_CHANNEL_PACKAGE_INCOMPATIBLE_REASON = "package-incompatible: package.json and pnpm-lock.yaml include @hcengineering/contact provider refs for email/telegram, but no compatible Huly Gmail or Telegram message SDK package/model is installed; local platform-api examples only expose contact.class.Channel provider values, not external message documents";
+var listExternalChannelMessages = (params) => Effect_exports.sync(
+  () => encodeListExternalChannelMessagesResult({
+    supported: false,
+    provider: params.provider,
+    channel: params.channel,
+    limit: params.limit ?? DEFAULT_EXTERNAL_CHANNEL_MESSAGE_LIMIT,
+    unsupportedReason: EXTERNAL_CHANNEL_PACKAGE_INCOMPATIBLE_REASON,
+    messages: []
+  })
+);
+
 // src/huly/operations/threads.ts
 var import_core31 = __toESM(require_lib4(), 1);
 var findReply = (client, channel, message, replyId) => Effect_exports.gen(function* () {
@@ -179806,6 +180201,17 @@ var channelTools = [
       listChannelMessages
     )
   },
+  {
+    name: "list_external_channel_messages",
+    description: "List read-only messages for an external Gmail or Telegram channel by channel name or ID. The limit defaults to 50 and is capped at 200. When this build does not include a compatible Huly external-message SDK/model for the requested provider, returns supported=false, an unsupportedReason, and an empty messages array; it never sends, replies, deletes, mutates, or returns fake messages.",
+    category: CATEGORY6,
+    inputSchema: listExternalChannelMessagesParamsJsonSchema,
+    handler: createToolHandler(
+      "list_external_channel_messages",
+      parseListExternalChannelMessagesParams,
+      listExternalChannelMessages
+    )
+  },
   {
     name: "send_channel_message",
     description: "Send a message to a Huly channel. Message body supports markdown formatting.",
@@ -186694,6 +187100,18 @@ var labelTools = [
 // src/huly/operations/leads.ts
 var import_core50 = __toESM(require_lib4(), 1);
 var funnelAsSpace = (funnel) => toRef(funnel._id);
+var statusInfosWithFallbacks = (statusRefs, statusDocs) => resolveByStatusRef(
+  statusRefs,
+  statusDocs,
+  (statusDoc) => ({
+    _id: statusDoc._id,
+    name: statusDoc.name
+  }),
+  (statusRef) => ({
+    _id: statusRef,
+    name: workflowStatusFromRef(statusRef).name
+  })
+);
 var markupBlobRefAsMarkupRef = (value3) => value3;
 var normalizeLeadIdentifier = (identifier2) => {
   const match16 = /^(?:LEAD-)?(\d+)$/i.exec(identifier2.trim());
@@ -186742,7 +187160,7 @@ var getFunnelStatuses = (client, funnel) => Effect_exports.gen(function* () {
       })
     );
   }
-  const statusRefs = projectType.statuses.map((status) => status._id);
+  const statusRefs = uniqueStatusRefs(projectType.statuses.map((status) => status._id));
   if (statusRefs.length === 0) {
     return yield* Effect_exports.fail(
       new HulyConnectionError({
@@ -186750,14 +187168,8 @@ var getFunnelStatuses = (client, funnel) => Effect_exports.gen(function* () {
       })
     );
   }
-  const statusDocs = yield* client.findAll(
-    core.class.Status,
-    { _id: { $in: [...statusRefs] } }
-  );
-  return statusDocs.map((doc) => ({
-    _id: doc._id,
-    name: doc.name
-  }));
+  const statusDocs = yield* findStatusDocs(client, statusRefs);
+  return statusInfosWithFallbacks(statusRefs, statusDocs);
 });
 var resolveStatusName2 = (statuses, statusId) => {
   const statusDoc = statuses.find((status) => status._id === statusId);
@@ -189553,14 +189965,15 @@ var toSpaceSummary = (space) => ({
   membersCount: Count.make(space.members.length),
   ownersCount: Count.make(space.owners?.length ?? 0)
 });
-var roleAssignments = (space) => {
-  if (space.roles === void 0) return void 0;
-  return Object.entries(space.roles).map(([roleId, members]) => ({
+var roleAssignments = (space, spaceType, validRoleIds) => {
+  if (spaceType === void 0) return void 0;
+  const entries2 = spaceRoleAssignmentEntries(space, spaceType, validRoleIds);
+  return entries2.length === 0 ? void 0 : entries2.map(([roleId, members]) => ({
     roleId: RoleId.make(roleId),
-    members: (members ?? []).map((member) => AccountUuid.make(member))
+    members: members.map((member) => AccountUuid.make(member))
   }));
 };
-var toSpaceDetail = (space) => ({
+var toSpaceDetail = (space, spaceType, validRoleIds = /* @__PURE__ */ new Set()) => ({
   id: SpaceId.make(space._id),
   name: space.name,
   description: space.description,
@@ -189571,7 +189984,7 @@ var toSpaceDetail = (space) => ({
   autoJoin: space.autoJoin,
   members: space.members.map((member) => AccountUuid.make(member)),
   owners: (space.owners ?? []).map((owner) => AccountUuid.make(owner)),
-  roleAssignments: roleAssignments(space)
+  roleAssignments: roleAssignments(space, spaceType, validRoleIds)
 });
 var spaceTypeSummary = (spaceType, descriptor3) => ({
   id: SpaceTypeId.make(spaceType._id),
@@ -189653,8 +190066,28 @@ var listSpaces = (params) => Effect_exports.gen(function* () {
 });
 var getSpace = (params) => Effect_exports.gen(function* () {
   const client = yield* HulyClient;
+  const diagnostics = yield* Diagnostics;
   const space = yield* findSpace(client, params);
-  return toSpaceDetail(space);
+  const spaceType = space.type === void 0 ? void 0 : yield* client.findOne(
+    core.class.SpaceType,
+    hulyQuery({ _id: toRef(space.type) })
+  );
+  const roles = spaceType === void 0 ? [] : yield* client.findAll(
+    core.class.Role,
+    hulyQuery({ attachedTo: spaceType._id }),
+    { limit: Math.max(spaceType.roles, 1) }
+  );
+  const validRoleIds = new Set(roles.map((role) => role._id));
+  if (spaceType !== void 0) {
+    const readResult = readSpaceRoleAssignmentEntries(space, spaceType, validRoleIds);
+    if (readResult.degradationReasons.length > 0) {
+      yield* diagnostics.warnAgent({
+        code: SpaceRoleAssignmentsDegradedWarningCode,
+        message: roleAssignmentDegradationMessage(readResult.degradationReasons)
+      });
+    }
+  }
+  return toSpaceDetail(space, spaceType, validRoleIds);
 });
 var listSpaceTypes = (params) => Effect_exports.gen(function* () {
   const client = yield* HulyClient;
@@ -189837,8 +190270,8 @@ var describeHulySpaceTypeCapabilities = (params) => Effect_exports.gen(function*
     roles: detail.roles,
     rolePermissions: detail.availablePermissions,
     assignmentShape: {
-      storedOnSpaceField: HulyConfigurationMetadataKey.make("roles"),
-      roleKeyField: HulyConfigurationMetadataKey.make("roleId"),
+      storedOnSpaceField: HulyConfigurationMetadataKey.make(`mixin:${detail.targetClass}`),
+      roleKeyField: HulyConfigurationMetadataKey.make("role._id"),
       memberValueShape: "accountUuidArrayOrUndefined",
       readProjectionTools: ["get_space"].map((tool) => HulyMcpToolName.make(tool))
     }
@@ -190172,6 +190605,104 @@ var searchTools = [
 ];
 
 // src/huly/operations/spaces-write.ts
+var roleClass = core.class.Role;
+var spaceTypeClass = core.class.SpaceType;
+var requireTypedSpaceType = (space) => Effect_exports.gen(function* () {
+  if (space.type === void 0) {
+    return yield* new SpaceNotTypedError({
+      id: SpaceId.make(space._id),
+      name: NonEmptyString2.make(space.name)
+    });
+  }
+  return SpaceTypeId.make(space.type);
+});
+var findSpaceType2 = (client, spaceType) => Effect_exports.gen(function* () {
+  const result = yield* client.findOne(
+    spaceTypeClass,
+    hulyQuery({ _id: toRef(spaceType) })
+  );
+  if (result === void 0) {
+    return yield* new SpaceRoleNotFoundError({
+      identifier: NonEmptyString2.make("SpaceType roles"),
+      spaceType
+    });
+  }
+  return result;
+});
+var resolveSpaceRole = (client, spaceType, role) => Effect_exports.gen(function* () {
+  const byId = yield* client.findOne(
+    roleClass,
+    hulyQuery({
+      _id: toRef(role),
+      attachedTo: toRef(spaceType)
+    })
+  );
+  if (byId !== void 0) return byId;
+  const matches = yield* client.findAll(
+    roleClass,
+    hulyQuery({
+      attachedTo: toRef(spaceType),
+      name: role
+    }),
+    { limit: 2 }
+  );
+  if (matches.length === 0) {
+    return yield* new SpaceRoleNotFoundError({
+      identifier: NonEmptyString2.make(role),
+      spaceType
+    });
+  }
+  if (matches.length > 1) {
+    return yield* new SpaceRoleIdentifierAmbiguousError({
+      identifier: NonEmptyString2.make(role),
+      spaceType,
+      matches: matches.map((match16) => ({
+        id: RoleId.make(match16._id),
+        name: NonEmptyString2.make(match16.name)
+      }))
+    });
+  }
+  return matches[0];
+});
+var findSpaceTypeRoles = (client, spaceType) => client.findAll(
+  roleClass,
+  hulyQuery({ attachedTo: spaceType._id }),
+  { limit: Math.max(spaceType.roles, 1) }
+);
+var writeSpaceRoleMembers = (client, space, spaceType, role, currentAssignments, members) => {
+  const mixin = spaceRoleAssignmentsMixin(spaceType);
+  const attributes = { ...currentAssignments, [role._id]: members };
+  const objectId = toRef(space._id);
+  const objectClass = toClassRef(space._class);
+  const objectSpace = toRef(space.space);
+  return hasSpaceRoleAssignmentMixin(space, spaceType) ? client.updateMixin(objectId, objectClass, objectSpace, mixin, attributes).pipe(Effect_exports.asVoid) : client.createMixin(objectId, objectClass, objectSpace, mixin, attributes).pipe(Effect_exports.asVoid);
+};
+var mutateSpaceRoleMembers = (params, mutateMembers) => Effect_exports.gen(function* () {
+  const client = yield* HulyClient;
+  const space = yield* findSpace(client, params);
+  const spaceType = yield* requireTypedSpaceType(space);
+  const spaceTypeDoc = yield* findSpaceType2(client, spaceType);
+  const role = yield* resolveSpaceRole(client, spaceType, params.role);
+  const validRoles = yield* findSpaceTypeRoles(client, spaceTypeDoc);
+  const resolvedMembers = yield* resolveMembers(client, params.members);
+  const currentAssignments = yield* strictSpaceRoleAssignments(
+    space,
+    spaceTypeDoc,
+    new Set(validRoles.map((validRole) => validRole._id))
+  );
+  const currentMembers = sortStrings(currentAssignments[role._id] ?? []).map(toAccountUuid);
+  const nextMembers = mutateMembers(currentMembers, resolvedMembers).map(toAccountUuid);
+  const changed = !arraysEqual(currentMembers, nextMembers);
+  if (changed) {
+    yield* writeSpaceRoleMembers(client, space, spaceTypeDoc, role, currentAssignments, nextMembers);
+  }
+  return {
+    id: SpaceId.make(space._id),
+    roleId: RoleId.make(role._id),
+    members: nextMembers.map((member) => AccountUuid.make(member)),
+    changed
+  };
+});
 var mutateSpaceMembers = (params, mutateMembers) => Effect_exports.gen(function* () {
   const client = yield* HulyClient;
   const space = yield* findSpace(client, params);
@@ -190224,6 +190755,9 @@ var setSpaceOwners = (params) => Effect_exports.gen(function* () {
     changed: changedOwners || changedMembers
   };
 });
+var setSpaceRoleMembers = (params) => mutateSpaceRoleMembers(params, (_currentMembers, resolvedMembers) => sortStrings(resolvedMembers).map(toAccountUuid));
+var addSpaceRoleMembers = (params) => mutateSpaceRoleMembers(params, mergeUniqueSortedAccountUuids);
+var removeSpaceRoleMembers = (params) => mutateSpaceRoleMembers(params, removeAccountUuids);
 
 // src/mcp/tools/spaces.ts
 var CATEGORY28 = "spaces";
@@ -190290,6 +190824,30 @@ var spaceTools = [
     category: CATEGORY28,
     inputSchema: setSpaceOwnersParamsJsonSchema,
     handler: createToolHandler("set_space_owners", parseSetSpaceOwnersParams, setSpaceOwners)
+  },
+  {
+    name: "set_space_role_members",
+    description: "Replace members assigned to one role on a typed Huly space while preserving all other role assignments. Role accepts a raw role _id or exact role name from the space's SpaceType. Members accept account UUID, exact email, or exact person display name; pass members=[] to clear this role.",
+    category: CATEGORY28,
+    inputSchema: setSpaceRoleMembersParamsJsonSchema,
+    annotations: { idempotentHint: true, destructiveHint: false },
+    handler: createToolHandler("set_space_role_members", parseSetSpaceRoleMembersParams, setSpaceRoleMembers)
+  },
+  {
+    name: "add_space_role_members",
+    description: "Idempotently add members to one role on a typed Huly space while preserving all other role assignments. Role accepts a raw role _id or exact role name from the space's SpaceType. Members accept account UUID, exact email, or exact person display name.",
+    category: CATEGORY28,
+    inputSchema: spaceRoleMemberMutationParamsJsonSchema,
+    annotations: { idempotentHint: true, destructiveHint: false },
+    handler: createToolHandler("add_space_role_members", parseSpaceRoleMemberMutationParams, addSpaceRoleMembers)
+  },
+  {
+    name: "remove_space_role_members",
+    description: "Idempotently remove members from one role on a typed Huly space while preserving all other role assignments. Role accepts a raw role _id or exact role name from the space's SpaceType. Members accept account UUID, exact email, or exact person display name.",
+    category: CATEGORY28,
+    inputSchema: spaceRoleMemberMutationParamsJsonSchema,
+    annotations: { idempotentHint: true, destructiveHint: false },
+    handler: createToolHandler("remove_space_role_members", parseSpaceRoleMemberMutationParams, removeSpaceRoleMembers)
   }
 ];
 
@@ -190591,7 +191149,7 @@ var STATUS_CATEGORIES = Object.values(STATUS_CATEGORY_BY_SDK_KEY).map((entry) =>
   name: entry.name
 }));
 var WORKFLOW_WARNING = "This changes workspace-level tracker configuration for every project using this project type.";
-var toCategoryValue = (category) => category === void 0 ? "unknown" : REF_TO_CATEGORY.get(category) ?? "unknown";
+var toCategoryValue = (category) => category === void 0 ? UnknownStatusCategoryValue : REF_TO_CATEGORY.get(category) ?? UnknownStatusCategoryValue;
 var encodeOrConnectionError2 = (schema, value3, operation) => Schema_exports.encode(schema)(value3).pipe(
   Effect_exports.as(value3),
   Effect_exports.mapError(
@@ -190607,9 +191165,17 @@ var uniqueProjectStatuses = (statuses) => statuses.reduce(
   (unique, status) => unique.some((existing) => sameProjectStatus(existing, status)) ? unique : [...unique, status],
   []
 );
-var getStatusDocs = (client, statusIds) => statusIds.length === 0 ? Effect_exports.succeed([]) : client.findAll(core.class.Status, hulyQuery({ _id: { $in: [...statusIds] } })).pipe(
-  Effect_exports.map(uniqueStatusDocs)
-);
+var getStatusDocs = (client, statusIds) => statusIds.length === 0 ? Effect_exports.succeed([]) : findStatusDocs(client, statusIds);
+var fallbackStatusDoc = (statusId) => ({
+  _id: statusId,
+  _class: core.class.Status,
+  space: core.space.Model,
+  modifiedOn: 0,
+  modifiedBy: core.account.System,
+  ofAttribute: tracker.attribute.IssueStatus,
+  name: workflowStatusFromRef(statusId).name
+});
+var statusDocsWithFallbacks = (statusIds, statusDocs) => resolveByStatusRef(statusIds, statusDocs, (statusDoc) => statusDoc, fallbackStatusDoc);
 var getTaskTypes = (client, taskTypeIds) => taskTypeIds.length === 0 ? Effect_exports.succeed([]) : client.findAll(task.class.TaskType, hulyQuery({ _id: { $in: [...taskTypeIds] } })).pipe(
   Effect_exports.map((result) => [...result])
 );
@@ -190628,7 +191194,9 @@ var getRecoverableStatusesByName = (client, name) => client.findAll(core.class.S
 );
 var loadWorkflowData = (client, projectType) => Effect_exports.gen(function* () {
   const taskTypes = yield* getTaskTypes(client, projectType.tasks);
-  const statuses = yield* getStatusDocs(client, uniqueStatusIds(projectType));
+  const statusIds = uniqueStatusIds(projectType);
+  const statusDocs = yield* getStatusDocs(client, statusIds);
+  const statuses = statusDocsWithFallbacks(statusIds, statusDocs);
   return { projectType, taskTypes, statuses };
 });
 var isDefaultClassicProjectType = (projectType) => projectType._id === tracker.ids.ClassingProjectType || projectType.classic || normalizeForComparison(projectType.name) === "classic";
@@ -193351,6 +193919,13 @@ var DRAIN_TIMEOUT_MS2 = 3e4;
 var NPM_FETCH_TIMEOUT_MS = 5e3;
 var NPM_PACKAGE_NAME2 = "@firfi/huly-mcp";
 var computeOutputBytes = (response) => response.content.reduce((sum2, c) => sum2 + c.text.length, 0);
+var withResourceWarnings = (result, warnings) => warnings.length === 0 ? result : {
+  ...result,
+  _meta: {
+    ...result._meta,
+    warnings
+  }
+};
 var deriveEditMode = (name, args2) => {
   if (name !== "edit_document" || args2 === void 0) return void 0;
   if (typeof args2 !== "object" || args2 === null || Array.isArray(args2)) return void 0;
@@ -193587,12 +194162,15 @@ var createMcpProtocolHandlers = (resolveClients, telemetry, registry2, getHulyCo
         resolveClients,
         (error2) => createResourceClientResolutionError(uri, error2)
       );
+      const diagnosticsScope = await Effect_exports.runPromise(makeDiagnosticsScope);
       const resourceRead = await Effect_exports.runPromiseExit(
         readHulyResource(uri).pipe(
-          Effect_exports.provideService(HulyClient, clients.hulyClient)
+          Effect_exports.provideService(HulyClient, clients.hulyClient),
+          Effect_exports.provideService(Diagnostics, diagnosticsScope.service)
         )
       );
-      if (Exit_exports.isSuccess(resourceRead)) return resourceRead.value;
+      const warnings = await Effect_exports.runPromise(diagnosticsScope.drainWarnings);
+      if (Exit_exports.isSuccess(resourceRead)) return withResourceWarnings(resourceRead.value, warnings);
       return throwResourceReadError(uri, resourceRead.cause);
     } finally {
       leave();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firfi/huly-mcp",
-  "version": "0.30.1",
+  "version": "0.31.1",
   "description": "MCP server for Huly integration",
   "mcpName": "io.github.dearlordylord/huly-mcp",
   "type": "module",