@hybridaione/hybridclaw 0.2.2 → 0.2.6

package/src/channels/discord/stream.ts

@@ -1,17 +1,25 @@
-import {
-  AttachmentBuilder,
-  type Message as DiscordMessage,
-} from 'discord.js';
+import type { AttachmentBuilder, Message as DiscordMessage } from 'discord.js';
 
 import { chunkMessage } from '../../chunk.js';
 import { logger } from '../../logger.js';
+import {
+  getHumanDelayMs,
+  type HumanDelayConfig,
+  sleep,
+} from './human-delay.js';
 
 interface DiscordSendChannel {
-  send: (payload: { content: string; files?: AttachmentBuilder[] }) => Promise<DiscordMessage>;
+  send: (payload: {
+    content: string;
+    files?: AttachmentBuilder[];
+  }) => Promise<DiscordMessage>;
 }
 
 interface DiscordEditMessage {
-  edit: (payload: { content: string; files?: AttachmentBuilder[] }) => Promise<DiscordMessage>;
+  edit: (payload: {
+    content: string;
+    files?: AttachmentBuilder[];
+  }) => Promise<DiscordMessage>;
   delete: () => Promise<unknown>;
 }
 
@@ -29,6 +37,7 @@ export interface DiscordStreamOptions {
   maxLines?: number;
   editIntervalMs?: number;
   onFirstMessage?: () => void;
+  humanDelay?: HumanDelayConfig;
 }
 
 const DEFAULT_MAX_CHARS = 1_800;
@@ -40,20 +49,30 @@ const RETRY_BASE_DELAY_MS = 500;
 function isRetryableDiscordError(error: unknown): boolean {
   const maybe = error as DiscordErrorLike;
   const status = maybe.status ?? maybe.httpStatus;
-  return status === 429 || (typeof status === 'number' && status >= 500 && status <= 599);
+  return (
+    status === 429 ||
+    (typeof status === 'number' && status >= 500 && status <= 599)
+  );
 }
 
 function extractRetryDelayMs(error: unknown, fallbackMs: number): number {
   const maybe = error as DiscordErrorLike;
   const retryAfterSeconds = maybe.retryAfter ?? maybe.data?.retry_after;
-  if (typeof retryAfterSeconds === 'number' && Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0) {
+  if (
+    typeof retryAfterSeconds === 'number' &&
+    Number.isFinite(retryAfterSeconds) &&
+    retryAfterSeconds > 0
+  ) {
     return Math.max(50, Math.ceil(retryAfterSeconds * 1_000));
   }
   const jitter = Math.floor(Math.random() * 250);
   return fallbackMs + jitter;
 }
 
-async function withDiscordRetry<T>(label: string, run: () => Promise<T>): Promise<T> {
+async function withDiscordRetry<T>(
+  label: string,
+  run: () => Promise<T>,
+): Promise<T> {
   let attempt = 0;
   let delayMs = RETRY_BASE_DELAY_MS;
   while (true) {
@@ -65,7 +84,10 @@ async function withDiscordRetry<T>(label: string, run: () => Promise<T>): Promis
         throw error;
       }
       const waitMs = extractRetryDelayMs(error, delayMs);
-      logger.warn({ label, attempt, waitMs, error }, 'Discord request failed; retrying');
+      logger.warn(
+        { label, attempt, waitMs, error },
+        'Discord request failed; retrying',
+      );
       await new Promise((resolve) => setTimeout(resolve, waitMs));
       delayMs = Math.min(delayMs * 2, 4_000);
     }
@@ -79,6 +101,7 @@ export class DiscordStreamManager {
   private readonly maxLines: number;
   private readonly editIntervalMs: number;
   private readonly onFirstMessage?: () => void;
+  private readonly humanDelay?: HumanDelayConfig;
 
   private readonly messages: DiscordEditMessage[] = [];
   private sentChunks: string[] = [];
@@ -93,8 +116,12 @@ export class DiscordStreamManager {
     this.channel = sourceMessage.channel as unknown as DiscordSendChannel;
     this.maxChars = Math.max(200, options?.maxChars ?? DEFAULT_MAX_CHARS);
     this.maxLines = Math.max(4, options?.maxLines ?? DEFAULT_MAX_LINES);
-    this.editIntervalMs = Math.max(250, options?.editIntervalMs ?? DEFAULT_EDIT_INTERVAL_MS);
+    this.editIntervalMs = Math.max(
+      250,
+      options?.editIntervalMs ?? DEFAULT_EDIT_INTERVAL_MS,
+    );
     this.onFirstMessage = options?.onFirstMessage;
+    this.humanDelay = options?.humanDelay;
   }
 
   hasSentMessages(): boolean {
@@ -125,9 +152,7 @@ export class DiscordStreamManager {
 
   fail(errorText: string): Promise<void> {
     if (this.closed) return Promise.resolve();
-    this.content = this.content
-      ? `${this.content}\n\n${errorText}`
-      : errorText;
+    this.content = this.content ? `${this.content}\n\n${errorText}` : errorText;
     if (this.flushTimer) {
       clearTimeout(this.flushTimer);
       this.flushTimer = null;
@@ -159,17 +184,18 @@ export class DiscordStreamManager {
   }
 
   private enqueue(task: () => Promise<void>): Promise<void> {
-    this.opQueue = this.opQueue
-      .then(task)
-      .catch((error) => {
-        logger.warn({ error }, 'Discord stream operation failed');
-      });
+    this.opQueue = this.opQueue.then(task).catch((error) => {
+      logger.warn({ error }, 'Discord stream operation failed');
+    });
     return this.opQueue;
   }
 
   private scheduleFlush(): void {
     if (this.flushTimer || this.closed) return;
-    const waitMs = Math.max(0, this.editIntervalMs - (Date.now() - this.lastEditAt));
+    const waitMs = Math.max(
+      0,
+      this.editIntervalMs - (Date.now() - this.lastEditAt),
+    );
     this.flushTimer = setTimeout(() => {
       this.flushTimer = null;
       void this.enqueue(async () => {
@@ -178,7 +204,10 @@ export class DiscordStreamManager {
     }, waitMs);
   }
 
-  private async sync(forceLastEdit: boolean, files?: AttachmentBuilder[]): Promise<void> {
+  private async sync(
+    forceLastEdit: boolean,
+    files?: AttachmentBuilder[],
+  ): Promise<void> {
     const chunks = chunkMessage(this.content, {
       maxChars: this.maxChars,
       maxLines: this.maxLines,
@@ -187,7 +216,9 @@ export class DiscordStreamManager {
     if (chunks.length === 0) {
       if (files && files.length > 0) {
         const fallback = 'Attached files:';
-        const sent = await withDiscordRetry('reply', () => this.sourceMessage.reply({ content: fallback, files }));
+        const sent = await withDiscordRetry('reply', () =>
+          this.sourceMessage.reply({ content: fallback, files }),
+        );
         this.messages.push(sent as unknown as DiscordEditMessage);
         this.sentChunks.push(fallback);
         this.onFirstMessage?.();
@@ -200,9 +231,20 @@ export class DiscordStreamManager {
       const isLast = i === chunks.length - 1;
 
       if (i >= this.messages.length) {
-        const sent = i === 0
-          ? await withDiscordRetry('reply', () => this.sourceMessage.reply({ content: chunk }))
-          : await withDiscordRetry('send', () => this.channel.send({ content: chunk }));
+        if (i > 0) {
+          const delayMs = getHumanDelayMs(this.humanDelay);
+          if (delayMs > 0) {
+            await sleep(delayMs);
+          }
+        }
+        const sent =
+          i === 0
+            ? await withDiscordRetry('reply', () =>
+                this.sourceMessage.reply({ content: chunk }),
+              )
+            : await withDiscordRetry('send', () =>
+                this.channel.send({ content: chunk }),
+              );
         this.messages.push(sent as unknown as DiscordEditMessage);
         this.sentChunks.push(chunk);
         this.onFirstMessage?.();
@@ -217,7 +259,9 @@ export class DiscordStreamManager {
         continue;
       }
 
-      await withDiscordRetry('edit', () => this.messages[i].edit({ content: chunk }));
+      await withDiscordRetry('edit', () =>
+        this.messages[i].edit({ content: chunk }),
+      );
       this.sentChunks[i] = chunk;
       this.lastEditAt = Date.now();
     }
@@ -232,7 +276,9 @@ export class DiscordStreamManager {
 
     if (files && files.length > 0) {
       const lastIndex = chunks.length - 1;
-      await withDiscordRetry('edit', () => this.messages[lastIndex].edit({ content: chunks[lastIndex], files }));
+      await withDiscordRetry('edit', () =>
+        this.messages[lastIndex].edit({ content: chunks[lastIndex], files }),
+      );
       this.sentChunks[lastIndex] = chunks[lastIndex];
       this.lastEditAt = Date.now();
     }

package/src/channels/discord/tool-actions.ts

@@ -33,7 +33,10 @@ export interface DiscordToolActionDependencies {
   getDiscordPresence: (userId: string) => CachedDiscordPresence | undefined;
 }
 
-function sanitizeDiscordId(rawValue: string | undefined, label: string): string {
+function sanitizeDiscordId(
+  rawValue: string | undefined,
+  label: string,
+): string {
   const value = (rawValue || '').trim();
   if (!/^\d{16,22}$/.test(value)) {
     throw new Error(`${label} must be a Discord snowflake id.`);
@@ -59,7 +62,9 @@ function scoreGuildMemberForLookup(member: GuildMember, query: string): number {
   const globalName = member.user.globalName?.toLowerCase() || '';
   const nickname = member.nickname?.toLowerCase() || '';
   const displayName = member.displayName?.toLowerCase() || '';
-  const candidates = [username, globalName, nickname, displayName].filter(Boolean);
+  const candidates = [username, globalName, nickname, displayName].filter(
+    Boolean,
+  );
 
   let score = 0;
   if (candidates.some((value) => value === q)) score += 3;
@@ -93,7 +98,10 @@ async function resolveGuildMemberIdFromLookup(params: {
   try {
     members = await guild.members.search({ query: searchQuery, limit: 25 });
   } catch {
-    const fetched = await guild.members.fetch({ query: searchQuery, limit: 25 });
+    const fetched = await guild.members.fetch({
+      query: searchQuery,
+      limit: 25,
+    });
     members = fetched;
   }
   let best: GuildMember | null = null;
@@ -146,14 +154,22 @@ async function runDiscordReadAction(
   const after = request.after?.trim();
   const around = request.around?.trim();
 
-  const query: { limit: number; before?: string; after?: string; around?: string } = { limit };
+  const query: {
+    limit: number;
+    before?: string;
+    after?: string;
+    around?: string;
+  } = { limit };
   if (before) query.before = before;
   if (after) query.after = after;
   if (around) query.around = around;
 
   const fetched = await channel.messages.fetch(query);
   const messages = Array.from(fetched.values())
-    .sort((a, b) => a.createdTimestamp - b.createdTimestamp || a.id.localeCompare(b.id))
+    .sort(
+      (a, b) =>
+        a.createdTimestamp - b.createdTimestamp || a.id.localeCompare(b.id),
+    )
     .map((message) => ({
       id: message.id,
       channelId: message.channelId,
@@ -175,13 +191,15 @@ async function runDiscordReadAction(
             displayName: message.member.displayName || null,
           }
         : null,
-      attachments: Array.from(message.attachments.values()).map((attachment) => ({
-        id: attachment.id,
-        name: attachment.name || null,
-        url: attachment.url,
-        contentType: attachment.contentType || null,
-        size: attachment.size,
-      })),
+      attachments: Array.from(message.attachments.values()).map(
+        (attachment) => ({
+          id: attachment.id,
+          name: attachment.name || null,
+          url: attachment.url,
+          contentType: attachment.contentType || null,
+          size: attachment.size,
+        }),
+      ),
       mentions: {
         users: Array.from(message.mentions.users.values()).map((user) => ({
           id: user.id,
@@ -192,12 +210,16 @@ async function runDiscordReadAction(
           id: role.id,
           name: role.name,
         })),
-        channels: Array.from(message.mentions.channels.values()).map((mentionedChannel) => ({
-          id: mentionedChannel.id,
-          name: 'name' in mentionedChannel && typeof mentionedChannel.name === 'string'
-            ? mentionedChannel.name
-            : null,
-        })),
+        channels: Array.from(message.mentions.channels.values()).map(
+          (mentionedChannel) => ({
+            id: mentionedChannel.id,
+            name:
+              'name' in mentionedChannel &&
+              typeof mentionedChannel.name === 'string'
+                ? mentionedChannel.name
+                : null,
+          }),
+        ),
       },
     }));
 
@@ -217,10 +239,7 @@ async function runDiscordMemberInfoAction(
   const activeClient = deps.requireDiscordClientReady();
   const guildId = sanitizeDiscordId(request.guildId, 'guildId');
   const userLookupRaw =
-    request.userId
-    || request.memberId
-    || request.user
-    || request.username;
+    request.userId || request.memberId || request.user || request.username;
   const resolvedUser = await resolveGuildMemberIdFromLookup({
     requireDiscordClientReady: deps.requireDiscordClientReady,
     guildId,
@@ -258,7 +277,9 @@ async function runDiscordMemberInfoAction(
       nickname: member.nickname || null,
       joinedAt: normalizeDate(member.joinedAt),
       premiumSince: normalizeDate(member.premiumSince),
-      communicationDisabledUntil: normalizeDate(member.communicationDisabledUntil),
+      communicationDisabledUntil: normalizeDate(
+        member.communicationDisabledUntil,
+      ),
       roles,
     },
     ...(presence
@@ -285,25 +306,43 @@ async function runDiscordChannelInfoAction(
     id: channel.id,
     type: channel.type,
     guildId: 'guildId' in channel ? channel.guildId || null : null,
-    name: 'name' in channel && typeof channel.name === 'string' ? channel.name : null,
+    name:
+      'name' in channel && typeof channel.name === 'string'
+        ? channel.name
+        : null,
     parentId: 'parentId' in channel ? channel.parentId || null : null,
-    topic: 'topic' in channel && typeof channel.topic === 'string' ? channel.topic : null,
-    nsfw: 'nsfw' in channel && typeof channel.nsfw === 'boolean' ? channel.nsfw : null,
+    topic:
+      'topic' in channel && typeof channel.topic === 'string'
+        ? channel.topic
+        : null,
+    nsfw:
+      'nsfw' in channel && typeof channel.nsfw === 'boolean'
+        ? channel.nsfw
+        : null,
     rateLimitPerUser:
-      'rateLimitPerUser' in channel && typeof channel.rateLimitPerUser === 'number'
+      'rateLimitPerUser' in channel &&
+      typeof channel.rateLimitPerUser === 'number'
         ? channel.rateLimitPerUser
         : null,
-    isTextBased: typeof channel.isTextBased === 'function' ? channel.isTextBased() : false,
-    isDMBased: typeof channel.isDMBased === 'function' ? channel.isDMBased() : false,
-    isThread: typeof channel.isThread === 'function' ? channel.isThread() : false,
-    lastMessageId: 'lastMessageId' in channel ? channel.lastMessageId || null : null,
+    isTextBased:
+      typeof channel.isTextBased === 'function' ? channel.isTextBased() : false,
+    isDMBased:
+      typeof channel.isDMBased === 'function' ? channel.isDMBased() : false,
+    isThread:
+      typeof channel.isThread === 'function' ? channel.isThread() : false,
+    lastMessageId:
+      'lastMessageId' in channel ? channel.lastMessageId || null : null,
   };
 
   if (typeof channel.isThread === 'function' && channel.isThread()) {
     channelData.archived =
-      'archived' in channel && typeof channel.archived === 'boolean' ? channel.archived : null;
+      'archived' in channel && typeof channel.archived === 'boolean'
+        ? channel.archived
+        : null;
     channelData.locked =
-      'locked' in channel && typeof channel.locked === 'boolean' ? channel.locked : null;
+      'locked' in channel && typeof channel.locked === 'boolean'
+        ? channel.locked
+        : null;
     channelData.ownerId = 'ownerId' in channel ? channel.ownerId || null : null;
   }
 
@@ -314,9 +353,9 @@ async function runDiscordChannelInfoAction(
   };
 }
 
-export function createDiscordToolActionRunner(deps: DiscordToolActionDependencies): (
-  request: DiscordToolActionRequest,
-) => Promise<Record<string, unknown>> {
+export function createDiscordToolActionRunner(
+  deps: DiscordToolActionDependencies,
+): (request: DiscordToolActionRequest) => Promise<Record<string, unknown>> {
   return async (request: DiscordToolActionRequest) => {
     switch (request.action) {
       case 'read':
@@ -326,7 +365,9 @@ export function createDiscordToolActionRunner(deps: DiscordToolActionDependencie
       case 'channel-info':
         return await runDiscordChannelInfoAction(request, deps);
       default:
-        throw new Error(`Unsupported Discord action: ${request.action as string}`);
+        throw new Error(
+          `Unsupported Discord action: ${request.action as string}`,
+        );
     }
   };
 }

package/src/channels/discord/typing.ts

@@ -0,0 +1,140 @@
+import type { Message as DiscordMessage } from 'discord.js';
+
+import { logger } from '../../logger.js';
+
+export type DiscordTypingPhase =
+  | 'received'
+  | 'thinking'
+  | 'toolUse'
+  | 'streaming'
+  | 'done';
+export type DiscordTypingMode = 'instant' | 'thinking' | 'streaming' | 'never';
+
+export interface TypingController {
+  setPhase: (phase: DiscordTypingPhase) => void;
+  stop: () => void;
+}
+
+interface CreateTypingControllerOptions {
+  keepaliveMs?: number;
+  ttlMs?: number;
+  stopGraceMs?: number;
+}
+
+const DEFAULT_KEEPALIVE_MS = 8_000;
+const DEFAULT_TTL_MS = 60_000;
+const DEFAULT_STOP_GRACE_MS = 500;
+
+function isTypingActiveForPhase(
+  mode: DiscordTypingMode,
+  phase: DiscordTypingPhase,
+): boolean {
+  if (mode === 'never') return false;
+  if (mode === 'instant') return phase !== 'done';
+  if (mode === 'thinking') return phase === 'thinking' || phase === 'toolUse';
+  return phase === 'streaming';
+}
+
+export function createTypingController(
+  message: DiscordMessage,
+  mode: DiscordTypingMode,
+  options?: CreateTypingControllerOptions,
+): TypingController {
+  if (mode === 'never') {
+    return {
+      setPhase: () => {},
+      stop: () => {},
+    };
+  }
+
+  const keepaliveMs = Math.max(
+    2_000,
+    Math.floor(options?.keepaliveMs ?? DEFAULT_KEEPALIVE_MS),
+  );
+  const ttlMs = Math.max(5_000, Math.floor(options?.ttlMs ?? DEFAULT_TTL_MS));
+  const stopGraceMs = Math.max(
+    0,
+    Math.floor(options?.stopGraceMs ?? DEFAULT_STOP_GRACE_MS),
+  );
+
+  let active = false;
+  let stopped = false;
+  let keepaliveTimer: ReturnType<typeof setInterval> | null = null;
+  let ttlTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const sendTyping = async (): Promise<void> => {
+    if (stopped || !active) return;
+    if (!('sendTyping' in message.channel)) return;
+    try {
+      await message.channel.sendTyping();
+    } catch (error) {
+      logger.debug(
+        { error, channelId: message.channelId },
+        'Failed to send typing indicator',
+      );
+    }
+  };
+
+  const clearTimers = (): void => {
+    if (keepaliveTimer) {
+      clearInterval(keepaliveTimer);
+      keepaliveTimer = null;
+    }
+    if (ttlTimer) {
+      clearTimeout(ttlTimer);
+      ttlTimer = null;
+    }
+    if (stopTimer) {
+      clearTimeout(stopTimer);
+      stopTimer = null;
+    }
+  };
+
+  const stopNow = (): void => {
+    active = false;
+    clearTimers();
+  };
+
+  const scheduleStop = (): void => {
+    if (stopped || !active) return;
+    if (stopTimer) return;
+    stopTimer = setTimeout(() => {
+      stopTimer = null;
+      stopNow();
+    }, stopGraceMs);
+  };
+
+  const ensureRunning = (): void => {
+    if (stopped) return;
+    if (stopTimer) {
+      clearTimeout(stopTimer);
+      stopTimer = null;
+    }
+    if (active) return;
+    active = true;
+    void sendTyping();
+    keepaliveTimer = setInterval(() => {
+      void sendTyping();
+    }, keepaliveMs);
+    ttlTimer = setTimeout(() => {
+      stopNow();
+    }, ttlMs);
+  };
+
+  return {
+    setPhase: (phase) => {
+      if (stopped) return;
+      if (isTypingActiveForPhase(mode, phase)) {
+        ensureRunning();
+      } else {
+        scheduleStop();
+      }
+    },
+    stop: () => {
+      if (stopped) return;
+      stopped = true;
+      stopNow();
+    },
+  };
+}

package/src/chunk.ts

@@ -82,7 +82,10 @@ function splitLongLine(line: string, maxChars: number): string[] {
   return pieces;
 }
 
-export function chunkMessage(text: string, opts?: ChunkMessageOptions): string[] {
+export function chunkMessage(
+  text: string,
+  opts?: ChunkMessageOptions,
+): string[] {
   const maxChars = Math.max(200, opts?.maxChars ?? DEFAULT_MAX_CHARS);
   const maxLines = Math.max(4, opts?.maxLines ?? DEFAULT_MAX_LINES);
   const normalized = (text || '').replace(/\r\n?/g, '\n');
@@ -120,15 +123,20 @@ export function chunkMessage(text: string, opts?: ChunkMessageOptions): string[]
   };
 
   const appendLine = (line: string): void => {
-    const addedChars = currentLines.length === 0 ? line.length : line.length + 1;
+    const addedChars =
+      currentLines.length === 0 ? line.length : line.length + 1;
     const nextChars = currentChars + addedChars;
     const nextLines = currentLines.length + 1;
-    if (currentLines.length > 0 && (nextChars > maxChars || nextLines > maxLines)) {
+    if (
+      currentLines.length > 0 &&
+      (nextChars > maxChars || nextLines > maxLines)
+    ) {
       flush(false);
     }
 
     currentLines.push(line);
-    currentChars = currentLines.length === 1 ? line.length : currentChars + line.length + 1;
+    currentChars =
+      currentLines.length === 1 ? line.length : currentChars + line.length + 1;
 
     if (isFenceLine(line)) {
       if (!openFence) {