@firfi/huly-mcp 0.30.0 → 0.31.0

package/README.md

@@ -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. |

package/dist/index.cjs

@@ -155260,6 +155260,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 +155345,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"),
@@ -165740,11 +165745,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",
@@ -165857,13 +165865,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 +165892,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 +166486,24 @@ var StdioServerTransport = class {
   }
 };
 
+// src/domain/schemas/tool-warnings.ts
+var ToolWarningCodeSchema = Schema_exports.Literal("status_metadata_unresolved").annotations({
+  identifier: "ToolWarningCode",
+  title: "ToolWarningCode",
+  description: "Machine-readable code for an agent-visible MCP tool warning."
+});
+var StatusMetadataUnresolvedWarningCode = ToolWarningCodeSchema.literals[0];
+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;
@@ -167252,6 +167288,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 +170136,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 +174624,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.0" : "0.0.0-dev";
+var VERSION = true ? "0.31.0" : "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"]
@@ -174616,6 +174775,22 @@ var findActivityMessage = (client, messageId) => findOneOrFail(
   () => new ActivityMessageNotFoundError({ messageId })
 );
 
+// src/huly/operations/thread-replies-shared.ts
+var removeThreadReply = (client, reply) => Effect_exports.gen(function* () {
+  const removeCollection = client.removeCollection;
+  if (removeCollection === void 0) {
+    return yield* new HulyError({ message: "Huly client does not support removeCollection" });
+  }
+  yield* removeCollection(
+    chunter.class.ThreadMessage,
+    reply.space,
+    reply._id,
+    reply.attachedTo,
+    reply.attachedToClass,
+    reply.collection
+  );
+});
+
 // src/huly/operations/activity-messages.ts
 var getActivityMessage = (params) => Effect_exports.gen(function* () {
   const client = yield* HulyClient;
@@ -174732,7 +174907,7 @@ var deleteActivityReply = (params) => Effect_exports.gen(function* () {
     hulyQuery({ _id: toRef(params.replyId) }),
     () => new ActivityMessageNotFoundError({ messageId: params.replyId })
   );
-  yield* client.removeDoc(chunter.class.ThreadMessage, reply.space, reply._id);
+  yield* removeThreadReply(client, reply);
   return { replyId: ActivityMessageId.make(reply._id), deleted: true };
 });
 
@@ -176166,7 +176341,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,
@@ -176179,7 +176354,7 @@ var workflowStatusFromRef = (statusRef) => {
   return {
     _id: statusRef,
     name,
-    category: "unknown"
+    category: UnknownStatusCategoryValue
   };
 };
 var uniqueStatusRefs = (refs) => refs.reduce(
@@ -176191,6 +176366,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(
@@ -176206,19 +176426,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 };
@@ -176582,19 +176791,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);
@@ -179497,6 +179714,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* () {
@@ -179601,11 +179831,7 @@ var updateThreadReply = (params) => Effect_exports.gen(function* () {
 var deleteThreadReply = (params) => Effect_exports.gen(function* () {
   const { channel, client, message } = yield* findChannelMessage(params);
   const reply = yield* findReply(client, channel, message, params.replyId);
-  yield* client.removeDoc(
-    chunter.class.ThreadMessage,
-    channel._id,
-    reply._id
-  );
+  yield* removeThreadReply(client, reply);
   return { id: ThreadReplyId.make(reply._id), deleted: true };
 });
 
@@ -179794,6 +180020,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.",
@@ -186682,6 +186919,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());
@@ -186730,7 +186979,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({
@@ -186738,14 +186987,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);
@@ -190579,7 +190822,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(
@@ -190595,9 +190838,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])
 );
@@ -190616,7 +190867,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";
@@ -193339,6 +193592,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;
@@ -193575,12 +193835,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.0",
+  "version": "0.31.0",
   "description": "MCP server for Huly integration",
   "mcpName": "io.github.dearlordylord/huly-mcp",
   "type": "module",