docs: document channel message access helpers

src/channels/inbound-event/classification.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel inbound event classifier.
+ *
+ * Decides whether group/channel activity should wake the agent or remain a passive room event.
+ */
 import { resolveAgentConfig } from "../../agents/agent-scope.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import type { ConversationFacts } from "../turn/types.js";

src/channels/inbound-event/context.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel inbound event context builder.
+ *
+ * Converts route, sender, command, media, and supplemental facts into finalized message context.
+ */
 import {
   commandTurnKindToSource,
   createCommandTurnContext,

src/channels/inbound-event/media.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel inbound media normalization.
+ *
+ * Converts plugin attachment metadata into aligned prompt/context media payload fields.
+ */
 import { normalizeOptionalString as normalizeString } from "@openclaw/normalization-core/string-coerce";
 import type { HistoryMediaEntry } from "../../auto-reply/reply/history.types.js";
 import type { InboundMediaFacts } from "../turn/types.js";

src/channels/mention-pattern-policy.ts

@@ -1,3 +1,8 @@
+/**
+ * Mention-pattern policy resolver.
+ *
+ * Applies provider and conversation allow/deny rules to mention pattern matching.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { MentionPatternsMode, MentionPatternsPolicyConfig } from "../config/types.messages.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";

src/channels/message-access/allowlist.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel ingress allowlist diagnostics.
+ *
+ * Merges allowlists, applies mutable identifier policy, and redacts access-graph facts.
+ */
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import type {
   ChannelIngressPolicyInput,

src/channels/message-access/decision.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel ingress decision graph builder.
+ *
+ * Evaluates route, sender, command, and mention gates into one admission decision.
+ */
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { resolveCommandAuthorizedFromAuthorizers } from "../command-gating.js";
 import { resolveInboundMentionDecision } from "../mention-gating.js";

src/channels/message-access/dm-allow-state.ts

@@ -1,9 +1,12 @@
+/**
+ * Direct-message allowlist audit state.
+ *
+ * Merges configured and persisted allowFrom entries for setup/status prompts.
+ */
 import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type { ChannelId } from "../plugins/types.public.js";
 import { readChannelIngressStoreAllowFromForDmPolicy } from "./runtime.js";
 
-// Builds the normalized DM allowlist state used by audits and setup prompts.
-// Config and persisted ingress-store entries are merged before counting users.
 export async function resolveDmAllowAuditState(params: {
   provider: ChannelId;
   accountId: string;

src/channels/message-access/runtime-access-groups.ts

@@ -1,3 +1,8 @@
+/**
+ * Runtime access-group resolution for channel ingress.
+ *
+ * Preserves symbolic access-group entries until dynamic membership facts are available.
+ */
 import {
   normalizeStringEntries,
   uniqueStrings,

src/channels/message-access/runtime-identity.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel ingress identity adapter helpers.
+ *
+ * Builds stable sender identity descriptors and normalizes matchable allowlist material.
+ */
 import type {
   ChannelIngressAdapter,
   ChannelIngressAdapterEntry,

src/channels/message-access/runtime-types.ts

@@ -1,3 +1,8 @@
+/**
+ * Public channel ingress runtime types.
+ *
+ * Defines identity descriptors, resolver inputs, route access, and resolved access results.
+ */
 import type { AccessGroupConfig } from "../../config/types.access-groups.js";
 import type {
   AccessGroupMembershipFact,

src/channels/message-access/runtime.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel ingress runtime resolver.
+ *
+ * Merges route, sender, command, access-group, and pairing-store facts before decision evaluation.
+ */
 import {
   normalizeStringEntries,
   uniqueStrings,

src/channels/message-access/sender-gates.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel ingress sender gate helpers.
+ *
+ * Evaluates DM and group sender policies against normalized allowlists.
+ */
 import {
   allowlistFailureReason,
   applyMutableIdentifierPolicy,

src/channels/message-access/state.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel ingress state resolver.
+ *
+ * Normalizes and matches route, sender, command, and access-group allowlists.
+ */
 import {
   normalizeStringEntries,
   uniqueStrings,

src/channels/message-access/types.ts

@@ -1,3 +1,8 @@
+/**
+ * Internal channel ingress access graph types.
+ *
+ * Defines redacted identifiers, allowlist diagnostics, route facts, and decision gates.
+ */
 import type { AccessGroupConfig } from "../../config/types.access-groups.js";
 import type { ChatChannelId } from "../ids.js";
 import type { InboundImplicitMentionKind, InboundMentionFacts } from "../mention-gating.js";

src/channels/message/adapter.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel message adapter definition helper.
+ *
+ * Supplies manual receive acknowledgement defaults while preserving adapter-specific types.
+ */
 import type {
   ChannelMessageAdapter,
   ChannelMessageAdapterShape,

src/channels/message/capabilities.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel message capability derivation.
+ *
+ * Computes durable-final delivery requirements from a concrete outbound payload.
+ */
 import type {
   DeriveDurableFinalDeliveryRequirementsParams,
   DurableFinalDeliveryCapability,

src/channels/message/contracts.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel message adapter contract verification helpers.
+ *
+ * Runs proof callbacks for declared durable, live-preview, live-message, and receive capabilities.
+ */
 import type {
   ChannelMessageAdapterShape,
   ChannelMessageLiveCapability,

src/channels/message/durable-receive.ts

@@ -1,3 +1,8 @@
+/**
+ * Durable inbound receive journal.
+ *
+ * Tracks accepted, pending, completed, and retryable inbound platform events.
+ */
 import type { PluginStateKeyedStore } from "../../plugin-state/plugin-state-store.types.js";
 import type { ChannelIngressQueue, ChannelIngressQueuePruneOptions } from "./ingress-queue.js";
 

src/channels/message/ingress-queue.ts

@@ -1,3 +1,8 @@
+/**
+ * Durable channel ingress queue.
+ *
+ * Stores, claims, completes, and tombstones inbound channel events in OpenClaw state.
+ */
 import { randomUUID } from "node:crypto";
 import type { DatabaseSync } from "node:sqlite";
 import type { Selectable } from "kysely";

src/channels/message/live.ts

@@ -1,3 +1,8 @@
+/**
+ * Live channel message state and preview finalization helpers.
+ *
+ * Tracks draft previews and converts them into finalized message receipts when possible.
+ */
 import type { LiveMessageState, MessageReceipt, RenderedMessageBatch } from "./types.js";
 export type { LiveMessagePhase, LiveMessageState } from "./types.js";
 

src/channels/message/outbound-bridge.ts

@@ -1,3 +1,8 @@
+/**
+ * Legacy outbound bridge adapter.
+ *
+ * Wraps old channel send functions in the newer channel message adapter contract.
+ */
 import { createMessageReceiptFromOutboundResults } from "./receipt.js";
 import type {
   ChannelMessageAdapterShape,

src/channels/message/receipt.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel message receipt normalization.
+ *
+ * Builds stable receipts from platform send results and nested adapter receipt data.
+ */
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type {
   MessageReceipt,

src/channels/message/receive.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel message receive acknowledgement context.
+ *
+ * Models ack/nack policy and idempotent receive state transitions for inbound events.
+ */
 import type { ChannelMessageReceiveAckPolicy } from "./types.js";
 
 /** Public alias for channel receive acknowledgement policy names. */

src/channels/message/rendered-batch.ts

@@ -1,3 +1,8 @@
+/**
+ * Rendered channel message batch planner.
+ *
+ * Summarizes reply payloads so delivery can pick adapter paths and recovery metadata.
+ */
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import type {
   RenderedMessageBatch,

src/channels/message/reply-pipeline.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel reply pipeline builder.
+ *
+ * Resolves source delivery mode, reply prefixing, typing callbacks, and payload transforms.
+ */
 import type { SourceReplyDeliveryMode } from "../../auto-reply/get-reply-options.types.js";
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import {

src/channels/message/send.ts

@@ -1,3 +1,8 @@
+/**
+ * Durable channel message sender.
+ *
+ * Sends rendered reply payloads, records live preview state, and classifies delivery outcomes.
+ */
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import { formatErrorMessage } from "../../infra/errors.js";
 import type { OutboundDeliveryResult } from "../../infra/outbound/deliver-types.js";

src/channels/message/state.ts

@@ -1,3 +1,8 @@
+/**
+ * Durable outbound message recovery state.
+ *
+ * Creates and classifies persisted send records after delivery interruptions.
+ */
 import type { DurableMessageSendIntent, MessageReceipt } from "./types.js";
 
 /** Durable send state stored for recovery and operator-visible delivery status. */

src/channels/message/types.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel message adapter and durability types.
+ *
+ * Defines receipts, live-message state, send contexts, and adapter capability contracts.
+ */
 import type { ReplyPayload } from "../../auto-reply/reply-payload.js";
 import type { ReplyToMode } from "../../config/types.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";

src/channels/model-overrides.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel-scoped model override resolver.
+ *
+ * Matches conversation ids, parent sessions, and wildcard config entries to model overrides.
+ */
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,

src/channels/native-command-session-targets.ts

@@ -1,3 +1,8 @@
+/**
+ * Native command session target resolver.
+ *
+ * Chooses storage and command target session keys for channel-native command events.
+ */
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /**

src/channels/plugins/account-helpers.ts

@@ -1,3 +1,8 @@
+/**
+ * Channel plugin account helper factory.
+ *
+ * Lists configured accounts and resolves default-account behavior for plugin configs.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";

src/channels/plugins/acp-configured-binding-consumer.ts

@@ -1,3 +1,8 @@
+/**
+ * ACP configured binding consumer.
+ *
+ * Converts channel configured-binding rules into persistent ACP binding records.
+ */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,