@hybridaione/hybridclaw 0.2.2 → 0.2.6

package/src/audit-events.ts

@@ -1,4 +1,10 @@
-import { appendAuditEvent, createAuditRunId, parseJsonObject, truncateAuditText, type AuditEventPayload } from './audit-trail.js';
+import {
+  type AuditEventPayload,
+  appendAuditEvent,
+  createAuditRunId,
+  parseJsonObject,
+  truncateAuditText,
+} from './audit-trail.js';
 import { logStructuredAuditEvent } from './db.js';
 import { logger } from './logger.js';
 import type { ToolExecution } from './types.js';
@@ -35,7 +41,8 @@ function summarizeToolResult(text: string): string {
   return truncateAuditText(text, 280);
 }
 
-const SENSITIVE_ARG_KEY_RE = /(pass(word)?|secret|token|api[_-]?key|authorization|cookie|credential|session)/i;
+const SENSITIVE_ARG_KEY_RE =
+  /(pass(word)?|secret|token|api[_-]?key|authorization|cookie|credential|session)/i;
 
 function sanitizeAuditArguments(toolName: string, value: unknown): unknown {
   if (Array.isArray(value)) {
@@ -69,7 +76,10 @@ export function emitToolExecutionAuditEvents(input: {
   toolExecutions.forEach((execution, index) => {
     const toolCallId = `${runId}:tool:${index + 1}`;
     const argumentsObject = parseJsonObject(execution.arguments || '{}');
-    const auditArguments = sanitizeAuditArguments(execution.name, argumentsObject);
+    const auditArguments = sanitizeAuditArguments(
+      execution.name,
+      argumentsObject,
+    );
 
     recordAuditEvent({
       sessionId,
@@ -90,11 +100,65 @@ export function emitToolExecutionAuditEvents(input: {
         action: `tool:${execution.name}`,
         resource: 'container.sandbox',
         allowed: !execution.blocked,
-        reason: execution.blockedReason || 'allowed',
+        reason:
+          execution.blockedReason ||
+          execution.approvalReason ||
+          (execution.approvalDecision
+            ? `approval:${execution.approvalDecision}`
+            : 'allowed'),
       },
     });
 
-    if (execution.blocked) {
+    const isRedApprovalAction =
+      execution.approvalTier === 'red' || execution.approvalBaseTier === 'red';
+    const hasApprovalDecision = typeof execution.approvalDecision === 'string';
+    if (isRedApprovalAction || hasApprovalDecision) {
+      const description =
+        execution.approvalReason ||
+        execution.blockedReason ||
+        `Approval flow for tool ${execution.name}`;
+      recordAuditEvent({
+        sessionId,
+        runId,
+        event: {
+          type: 'approval.request',
+          toolCallId,
+          action: execution.approvalActionKey || `tool:${execution.name}`,
+          description,
+          policyName: 'trusted-coworker',
+        },
+      });
+
+      const decision = execution.approvalDecision;
+      const approved =
+        decision === 'approved_once' ||
+        decision === 'approved_session' ||
+        decision === 'approved_agent' ||
+        decision === 'promoted';
+      const pending = decision === 'required';
+      if (decision && decision !== 'auto' && decision !== 'implicit') {
+        recordAuditEvent({
+          sessionId,
+          runId,
+          event: {
+            type: 'approval.response',
+            toolCallId,
+            action: execution.approvalActionKey || `tool:${execution.name}`,
+            description: pending
+              ? `${description} (pending user response)`
+              : description,
+            approved,
+            approvedBy: pending
+              ? 'pending-user-response'
+              : approved
+                ? 'local-user'
+                : 'policy-engine',
+            method: pending || approved ? 'prompt' : 'policy',
+            policyName: 'trusted-coworker',
+          },
+        });
+      }
+    } else if (execution.blocked) {
       recordAuditEvent({
         sessionId,
         runId,

package/src/audit-trail.ts

@@ -92,10 +92,12 @@ function stableStringify(value: unknown): string {
   const type = typeof value;
 
   if (type === 'string') return JSON.stringify(value);
-  if (type === 'number') return Number.isFinite(value as number) ? String(value) : 'null';
+  if (type === 'number')
+    return Number.isFinite(value as number) ? String(value) : 'null';
   if (type === 'boolean') return value ? 'true' : 'false';
   if (type === 'bigint') return JSON.stringify((value as bigint).toString());
-  if (type === 'undefined' || type === 'function' || type === 'symbol') return 'null';
+  if (type === 'undefined' || type === 'function' || type === 'symbol')
+    return 'null';
 
   if (Array.isArray(value)) {
     return `[${value.map((entry) => stableStringify(entry === undefined ? null : entry)).join(',')}]`;
@@ -106,7 +108,12 @@ function stableStringify(value: unknown): string {
   const keys = Object.keys(obj).sort((a, b) => a.localeCompare(b));
   for (const key of keys) {
     const raw = obj[key];
-    if (raw === undefined || typeof raw === 'function' || typeof raw === 'symbol') continue;
+    if (
+      raw === undefined ||
+      typeof raw === 'function' ||
+      typeof raw === 'symbol'
+    )
+      continue;
     parts.push(`${JSON.stringify(key)}:${stableStringify(raw)}`);
   }
   return `{${parts.join(',')}}`;
@@ -167,7 +174,10 @@ function computeWireRecordHash(record: Omit<WireRecord, '_hash'>): string {
   return sha256(stableStringify(record));
 }
 
-function readSessionStateFromDisk(sessionId: string, filePath: string): SessionAuditState {
+function readSessionStateFromDisk(
+  sessionId: string,
+  filePath: string,
+): SessionAuditState {
   if (!fs.existsSync(filePath) || fs.statSync(filePath).size === 0) {
     const metadata: WireMetadataRecord = {
       type: 'metadata',
@@ -184,7 +194,10 @@ function readSessionStateFromDisk(sessionId: string, filePath: string): SessionA
   }
 
   const raw = fs.readFileSync(filePath, 'utf-8');
-  const lines = raw.split('\n').map((line) => line.trim()).filter(Boolean);
+  const lines = raw
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
   if (lines.length === 0) {
     const metadata: WireMetadataRecord = {
       type: 'metadata',
@@ -209,8 +222,14 @@ function readSessionStateFromDisk(sessionId: string, filePath: string): SessionA
       const metadata: WireMetadataRecord = {
         type: 'metadata',
         protocolVersion: AUDIT_PROTOCOL_VERSION,
-        sessionId: typeof firstParsed.sessionId === 'string' ? firstParsed.sessionId : sessionId,
-        createdAt: typeof firstParsed.createdAt === 'string' ? firstParsed.createdAt : new Date().toISOString(),
+        sessionId:
+          typeof firstParsed.sessionId === 'string'
+            ? firstParsed.sessionId
+            : sessionId,
+        createdAt:
+          typeof firstParsed.createdAt === 'string'
+            ? firstParsed.createdAt
+            : new Date().toISOString(),
       };
       lastHash = computeMetadataHash(metadata);
       startIndex = 1;
@@ -223,10 +242,10 @@ function readSessionStateFromDisk(sessionId: string, filePath: string): SessionA
     try {
       const parsed = JSON.parse(lines[i]) as Partial<WireRecord>;
       if (
-        typeof parsed.seq === 'number'
-        && Number.isFinite(parsed.seq)
-        && typeof parsed._hash === 'string'
-        && parsed._hash
+        typeof parsed.seq === 'number' &&
+        Number.isFinite(parsed.seq) &&
+        typeof parsed._hash === 'string' &&
+        parsed._hash
       ) {
         seq = parsed.seq;
         lastHash = parsed._hash;
@@ -319,7 +338,8 @@ export function verifyAuditSessionChain(sessionId: string): AuditVerifyResult {
       const metadata: WireMetadataRecord = {
         type: 'metadata',
         protocolVersion: AUDIT_PROTOCOL_VERSION,
-        sessionId: typeof first.sessionId === 'string' ? first.sessionId : sessionId,
+        sessionId:
+          typeof first.sessionId === 'string' ? first.sessionId : sessionId,
         createdAt: typeof first.createdAt === 'string' ? first.createdAt : '',
       };
       expectedPrevHash = computeMetadataHash(metadata);
@@ -335,12 +355,16 @@ export function verifyAuditSessionChain(sessionId: string): AuditVerifyResult {
     try {
       parsed = JSON.parse(lines[i]) as WireRecord;
     } catch (err) {
-      errors.push(`Line ${lineNo}: invalid JSON (${err instanceof Error ? err.message : 'parse failure'}).`);
+      errors.push(
+        `Line ${lineNo}: invalid JSON (${err instanceof Error ? err.message : 'parse failure'}).`,
+      );
       continue;
     }
 
     if (parsed.version !== AUDIT_PROTOCOL_VERSION) {
-      errors.push(`Line ${lineNo}: unsupported version "${String(parsed.version)}".`);
+      errors.push(
+        `Line ${lineNo}: unsupported version "${String(parsed.version)}".`,
+      );
       continue;
     }
     if (!Number.isFinite(parsed.seq) || parsed.seq <= 0) {
@@ -348,7 +372,9 @@ export function verifyAuditSessionChain(sessionId: string): AuditVerifyResult {
       continue;
     }
     if (parsed.seq !== expectedSeq) {
-      errors.push(`Line ${lineNo}: expected seq ${expectedSeq}, got ${parsed.seq}.`);
+      errors.push(
+        `Line ${lineNo}: expected seq ${expectedSeq}, got ${parsed.seq}.`,
+      );
     }
     if (parsed._prevHash !== expectedPrevHash) {
       errors.push(`Line ${lineNo}: previous hash mismatch.`);

package/src/channels/discord/attachments.ts

@@ -1,8 +1,10 @@
+import { randomUUID } from 'crypto';
+import type {
+  Attachment as DiscordAttachment,
+  Message as DiscordMessage,
+} from 'discord.js';
 import fs from 'fs';
 import path from 'path';
-import { randomUUID } from 'crypto';
-
-import type { Attachment as DiscordAttachment, Message as DiscordMessage } from 'discord.js';
 
 import { DATA_DIR } from '../../config.js';
 import { logger } from '../../logger.js';
@@ -11,7 +13,9 @@ import type { MediaContextItem } from '../../types.js';
 const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
 const MAX_ATTACHMENT_CONTEXT_CHARS = 16_000;
 const MAX_SINGLE_ATTACHMENT_CHARS = 8_000;
-const DISCORD_MEDIA_CACHE_DIR = path.resolve(path.join(DATA_DIR, 'discord-media-cache'));
+const DISCORD_MEDIA_CACHE_DIR = path.resolve(
+  path.join(DATA_DIR, 'discord-media-cache'),
+);
 const CONTAINER_DISCORD_MEDIA_CACHE_DIR = '/discord-media-cache';
 const DISCORD_ATTACHMENT_FETCH_TIMEOUT_MS = 12_000;
 const DISCORD_CDN_HOST_PATTERNS: RegExp[] = [
@@ -26,10 +30,20 @@ export interface AttachmentContextResult {
   media: MediaContextItem[];
 }
 
-export function looksLikeTextAttachment(name: string, contentType: string): boolean {
+export function looksLikeTextAttachment(
+  name: string,
+  contentType: string,
+): boolean {
   if (contentType.startsWith('text/')) return true;
-  if (contentType.includes('json') || contentType.includes('xml') || contentType.includes('yaml')) return true;
-  return /\.(txt|md|markdown|json|ya?ml|js|jsx|ts|tsx|py|rb|go|rs|java|c|cpp|h|hpp|cs|php|html?|css|scss|sql|log|csv)$/i.test(name);
+  if (
+    contentType.includes('json') ||
+    contentType.includes('xml') ||
+    contentType.includes('yaml')
+  )
+    return true;
+  return /\.(txt|md|markdown|json|ya?ml|js|jsx|ts|tsx|py|rb|go|rs|java|c|cpp|h|hpp|cs|php|html?|css|scss|sql|log|csv)$/i.test(
+    name,
+  );
 }
 
 function looksLikeImageAttachment(name: string, contentType: string): boolean {
@@ -38,14 +52,19 @@ function looksLikeImageAttachment(name: string, contentType: string): boolean {
 }
 
 function sanitizeAttachmentFilename(name: string): string {
-  const base = name.trim().replace(/[^\w.\-]+/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+  const base = name
+    .trim()
+    .replace(/[^\w.-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
   const bounded = base.slice(0, 96);
   return bounded || 'attachment';
 }
 
 function normalizeAttachmentPathForContainer(hostPath: string): string | null {
   const relative = path.relative(DISCORD_MEDIA_CACHE_DIR, hostPath);
-  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative))
+    return null;
   return `${CONTAINER_DISCORD_MEDIA_CACHE_DIR}/${relative.replace(/\\/g, '/')}`;
 }
 
@@ -57,10 +76,15 @@ function isAllowedDiscordAttachmentUrl(rawUrl: string): boolean {
     return false;
   }
   if (parsed.protocol !== 'https:') return false;
-  return DISCORD_CDN_HOST_PATTERNS.some((pattern) => pattern.test(parsed.hostname));
+  return DISCORD_CDN_HOST_PATTERNS.some((pattern) =>
+    pattern.test(parsed.hostname),
+  );
 }
 
-async function fetchAttachmentText(url: string, maxChars: number): Promise<string | null> {
+async function fetchAttachmentText(
+  url: string,
+  maxChars: number,
+): Promise<string | null> {
   try {
     const response = await fetch(url);
     if (!response.ok) return null;
@@ -102,7 +126,10 @@ async function cacheDiscordImageAttachment(params: {
     }
 
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), DISCORD_ATTACHMENT_FETCH_TIMEOUT_MS);
+    const timer = setTimeout(
+      () => controller.abort(),
+      DISCORD_ATTACHMENT_FETCH_TIMEOUT_MS,
+    );
     try {
       const response = await fetch(candidateUrl, { signal: controller.signal });
       if (!response.ok) {
@@ -110,17 +137,27 @@ async function cacheDiscordImageAttachment(params: {
         continue;
       }
 
-      const resolvedMime = String(response.headers.get('content-type') || fallbackMimeType || '')
+      const resolvedMime = String(
+        response.headers.get('content-type') || fallbackMimeType || '',
+      )
         .split(';')[0]
         .trim()
         .toLowerCase();
       if (!resolvedMime.startsWith('image/')) {
-        fetchErrors.push(`invalid_type:${resolvedMime || 'unknown'}@${candidateUrl}`);
+        fetchErrors.push(
+          `invalid_type:${resolvedMime || 'unknown'}@${candidateUrl}`,
+        );
         continue;
       }
 
-      const contentLength = Number.parseInt(response.headers.get('content-length') || '', 10);
-      if (Number.isFinite(contentLength) && contentLength > MAX_ATTACHMENT_BYTES) {
+      const contentLength = Number.parseInt(
+        response.headers.get('content-length') || '',
+        10,
+      );
+      if (
+        Number.isFinite(contentLength) &&
+        contentLength > MAX_ATTACHMENT_BYTES
+      ) {
         fetchErrors.push(`too_large_header:${contentLength}@${candidateUrl}`);
         continue;
       }
@@ -155,18 +192,22 @@ async function cacheDiscordImageAttachment(params: {
     }
   }
 
-  const fallbackUrl = sourceCandidates.find((url) => isAllowedDiscordAttachmentUrl(url))
-    || sourceCandidates[0]
-    || '';
+  const fallbackUrl =
+    sourceCandidates.find((url) => isAllowedDiscordAttachmentUrl(url)) ||
+    sourceCandidates[0] ||
+    '';
   return {
     path: null,
     sourceUrl: fallbackUrl,
     mimeType: fallbackMimeType,
-    cacheError: fetchErrors.length > 0 ? fetchErrors.join(' | ') : 'cache_failed',
+    cacheError:
+      fetchErrors.length > 0 ? fetchErrors.join(' | ') : 'cache_failed',
   };
 }
 
-export async function buildAttachmentContext(messages: DiscordMessage[]): Promise<AttachmentContextResult> {
+export async function buildAttachmentContext(
+  messages: DiscordMessage[],
+): Promise<AttachmentContextResult> {
   const lines: string[] = [];
   const media: MediaContextItem[] = [];
   let remainingChars = MAX_ATTACHMENT_CONTEXT_CHARS;
@@ -179,7 +220,9 @@ export async function buildAttachmentContext(messages: DiscordMessage[]): Promis
       const size = attachment.size || 0;
       const contentType = (attachment.contentType || '').toLowerCase();
       if (size > MAX_ATTACHMENT_BYTES) {
-        lines.push(`- ${name}: skipped (size ${size} bytes exceeds 10MB limit)`);
+        lines.push(
+          `- ${name}: skipped (size ${size} bytes exceeds 10MB limit)`,
+        );
         if (looksLikeImageAttachment(name, contentType)) {
           mediaOrder += 1;
           media.push({
@@ -220,7 +263,9 @@ export async function buildAttachmentContext(messages: DiscordMessage[]): Promis
           filename: name,
         });
         if (cached.path) {
-          lines.push(`- ${name}: image attachment cached (${size} bytes, ${cached.mimeType || contentType || 'unknown type'})`);
+          lines.push(
+            `- ${name}: image attachment cached (${size} bytes, ${cached.mimeType || contentType || 'unknown type'})`,
+          );
           logger.info(
             {
               messageId: msg.id,
@@ -233,7 +278,9 @@ export async function buildAttachmentContext(messages: DiscordMessage[]): Promis
             'Discord image attachment cached successfully',
           );
         } else {
-          lines.push(`- ${name}: image attachment (cache failed, using URL fallback)`);
+          lines.push(
+            `- ${name}: image attachment (cache failed, using URL fallback)`,
+          );
           logger.warn(
             {
               messageId: msg.id,
@@ -250,7 +297,10 @@ export async function buildAttachmentContext(messages: DiscordMessage[]): Promis
       }
 
       if (looksLikeTextAttachment(name, contentType)) {
-        const maxChars = Math.min(MAX_SINGLE_ATTACHMENT_CHARS, Math.max(500, remainingChars));
+        const maxChars = Math.min(
+          MAX_SINGLE_ATTACHMENT_CHARS,
+          Math.max(500, remainingChars),
+        );
         const text = await fetchAttachmentText(attachment.url, maxChars);
         if (!text) {
           lines.push(`- ${name}: text attachment (failed to read content)`);
@@ -261,7 +311,9 @@ export async function buildAttachmentContext(messages: DiscordMessage[]): Promis
         remainingChars -= block.length;
         lines.push(block);
         if (remainingChars <= 0) {
-          lines.push('- Additional attachment content omitted (context budget reached).');
+          lines.push(
+            '- Additional attachment content omitted (context budget reached).',
+          );
           return {
             context: `[Attachments]\n${lines.join('\n')}\n\n`,
             media,
@@ -270,7 +322,9 @@ export async function buildAttachmentContext(messages: DiscordMessage[]): Promis
         continue;
       }
 
-      lines.push(`- ${name}: attachment (${size} bytes, ${contentType || 'unknown type'})`);
+      lines.push(
+        `- ${name}: attachment (${size} bytes, ${contentType || 'unknown type'})`,
+      );
     }
   }
 

package/src/channels/discord/debounce.ts

@@ -0,0 +1,25 @@
+const CONTROL_COMMAND_RE = /^\/(stop|pause|clear|cancel|resume)\b/i;
+
+export const DEFAULT_DEBOUNCE_MS = 2_500;
+export const DEFAULT_DEBOUNCE_MAX_BUFFER = 5;
+
+export function resolveInboundDebounceMs(
+  globalDebounceMs: number,
+  channelOverrideMs?: number,
+): number {
+  const selected = channelOverrideMs ?? globalDebounceMs;
+  return Math.max(0, Math.floor(selected));
+}
+
+export function shouldDebounceInbound(params: {
+  content: string;
+  hasAttachments: boolean;
+  isPrefixedCommand: boolean;
+}): boolean {
+  const normalized = params.content.trim();
+  if (!normalized) return false;
+  if (params.hasAttachments) return false;
+  if (params.isPrefixedCommand) return false;
+  if (CONTROL_COMMAND_RE.test(normalized)) return false;
+  return true;
+}

package/src/channels/discord/delivery.ts

@@ -1,9 +1,21 @@
-import { AttachmentBuilder, type ChatInputCommandInteraction, type Message as DiscordMessage } from 'discord.js';
+import type {
+  AttachmentBuilder,
+  ChatInputCommandInteraction,
+  Message as DiscordMessage,
+} from 'discord.js';
 
 import { chunkMessage } from '../../chunk.js';
-import { rewriteUserMentions, type MentionLookup } from './mentions.js';
+import {
+  getHumanDelayMs,
+  type HumanDelayConfig,
+  sleep,
+} from './human-delay.js';
+import { type MentionLookup, rewriteUserMentions } from './mentions.js';
 
-export type DiscordRetryFn = <T>(label: string, fn: () => Promise<T>) => Promise<T>;
+export type DiscordRetryFn = <T>(
+  label: string,
+  fn: () => Promise<T>,
+) => Promise<T>;
 
 export function buildResponseText(text: string, toolsUsed?: string[]): string {
   let body = text;
@@ -27,12 +39,16 @@ export function prepareChunkedPayloads(
   files?: AttachmentBuilder[],
   mentionLookup?: MentionLookup,
 ): { content: string; files?: AttachmentBuilder[] }[] {
-  const prepared = mentionLookup ? rewriteUserMentions(text, mentionLookup) : text;
+  const prepared = mentionLookup
+    ? rewriteUserMentions(text, mentionLookup)
+    : text;
   const chunks = chunkMessage(prepared, { maxChars: 1_900, maxLines: 20 });
   const safeChunks = chunks.length > 0 ? chunks : ['(no content)'];
   return safeChunks.map((content, i) => ({
     content,
-    ...(i === safeChunks.length - 1 && files && files.length > 0 ? { files } : {}),
+    ...(i === safeChunks.length - 1 && files && files.length > 0
+      ? { files }
+      : {}),
   }));
 }
 
@@ -42,6 +58,7 @@ export async function sendChunkedReply(params: {
   withRetry: DiscordRetryFn;
   files?: AttachmentBuilder[];
   mentionLookup?: MentionLookup;
+  humanDelay?: HumanDelayConfig;
 }): Promise<void> {
   const payloads = prepareChunkedPayloads(
     params.text,
@@ -52,9 +69,20 @@ export async function sendChunkedReply(params: {
     if (i === 0) {
       await params.withRetry('reply', () => params.msg.reply(payloads[i]));
     } else {
-      await params.withRetry('send', () => (params.msg.channel as unknown as {
-        send: (next: { content: string; files?: AttachmentBuilder[] }) => Promise<void>;
-      }).send(payloads[i]));
+      const delayMs = getHumanDelayMs(params.humanDelay);
+      if (delayMs > 0) {
+        await sleep(delayMs);
+      }
+      await params.withRetry('send', () =>
+        (
+          params.msg.channel as unknown as {
+            send: (next: {
+              content: string;
+              files?: AttachmentBuilder[];
+            }) => Promise<void>;
+          }
+        ).send(payloads[i]),
+      );
     }
   }
 }
@@ -65,14 +93,24 @@ export async function sendChunkedDirectReply(params: {
   withRetry: DiscordRetryFn;
   files?: AttachmentBuilder[];
   mentionLookup?: MentionLookup;
+  humanDelay?: HumanDelayConfig;
 }): Promise<void> {
   const payloads = prepareChunkedPayloads(
     params.text,
     params.files,
     params.mentionLookup,
   );
-  const dm = await params.withRetry('dm-open', () => params.msg.author.createDM());
-  for (const payload of payloads) {
+  const dm = await params.withRetry('dm-open', () =>
+    params.msg.author.createDM(),
+  );
+  for (let i = 0; i < payloads.length; i += 1) {
+    if (i > 0) {
+      const delayMs = getHumanDelayMs(params.humanDelay);
+      if (delayMs > 0) {
+        await sleep(delayMs);
+      }
+    }
+    const payload = payloads[i];
     await params.withRetry('dm-send', () => dm.send(payload));
   }
 }
@@ -88,12 +126,18 @@ export async function sendChunkedInteractionReply(params: {
     const payload = { ...payloads[i], ephemeral: true };
     if (i === 0) {
       if (params.interaction.replied || params.interaction.deferred) {
-        await params.withRetry('interaction-followup', () => params.interaction.followUp(payload));
+        await params.withRetry('interaction-followup', () =>
+          params.interaction.followUp(payload),
+        );
       } else {
-        await params.withRetry('interaction-reply', () => params.interaction.reply(payload));
+        await params.withRetry('interaction-reply', () =>
+          params.interaction.reply(payload),
+        );
       }
       continue;
     }
-    await params.withRetry('interaction-followup', () => params.interaction.followUp(payload));
+    await params.withRetry('interaction-followup', () =>
+      params.interaction.followUp(payload),
+    );
   }
 }

package/src/channels/discord/human-delay.ts

@@ -0,0 +1,48 @@
+export interface HumanDelayConfig {
+  mode: 'off' | 'natural' | 'custom';
+  minMs?: number;
+  maxMs?: number;
+}
+
+export interface ResolvedHumanDelayConfig {
+  mode: 'off' | 'natural' | 'custom';
+  minMs: number;
+  maxMs: number;
+}
+
+export const DEFAULT_HUMAN_DELAY_MIN_MS = 800;
+export const DEFAULT_HUMAN_DELAY_MAX_MS = 2_500;
+
+export function resolveHumanDelayConfig(
+  config?: HumanDelayConfig,
+): ResolvedHumanDelayConfig {
+  const mode = config?.mode ?? 'natural';
+  const minMs = Math.max(
+    0,
+    Math.floor(config?.minMs ?? DEFAULT_HUMAN_DELAY_MIN_MS),
+  );
+  const rawMax = Math.max(
+    0,
+    Math.floor(config?.maxMs ?? DEFAULT_HUMAN_DELAY_MAX_MS),
+  );
+  const maxMs = Math.max(minMs, rawMax);
+  return {
+    mode,
+    minMs,
+    maxMs,
+  };
+}
+
+export function getHumanDelayMs(config?: HumanDelayConfig): number {
+  const resolved = resolveHumanDelayConfig(config);
+  if (resolved.mode === 'off') return 0;
+  if (resolved.maxMs <= resolved.minMs) return resolved.minMs;
+  const span = resolved.maxMs - resolved.minMs + 1;
+  return resolved.minMs + Math.floor(Math.random() * span);
+}
+
+export async function sleep(ms: number): Promise<void> {
+  const waitMs = Math.max(0, Math.floor(ms));
+  if (waitMs <= 0) return;
+  await new Promise((resolve) => setTimeout(resolve, waitMs));
+}