discoclaw 0.1.0

package/dist/discord/health-command.test.js

@@ -0,0 +1,195 @@
+import { describe, expect, it } from 'vitest';
+import { MetricsRegistry } from '../observability/metrics.js';
+import { parseHealthCommand, renderHealthReport, renderHealthToolsReport } from './health-command.js';
+describe('parseHealthCommand', () => {
+    it('parses supported command forms', () => {
+        expect(parseHealthCommand('!health')).toBe('basic');
+        expect(parseHealthCommand('  !health   verbose ')).toBe('verbose');
+        expect(parseHealthCommand('!health tools')).toBe('tools');
+        expect(parseHealthCommand('!memory show')).toBeNull();
+    });
+});
+describe('renderHealthReport', () => {
+    it('renders basic and verbose reports without secrets', () => {
+        const metrics = new MetricsRegistry();
+        metrics.increment('discord.message.received');
+        metrics.recordInvokeStart('message');
+        metrics.recordInvokeResult('message', 120, false, 'timed out');
+        const baseConfig = {
+            runtimeModel: 'opus',
+            runtimeTimeoutMs: 60000,
+            runtimeTools: ['Read', 'Edit'],
+            useRuntimeSessions: true,
+            toolAwareStreaming: true,
+            maxConcurrentInvocations: 3,
+            discordActionsEnabled: true,
+            summaryEnabled: true,
+            durableMemoryEnabled: true,
+            messageHistoryBudget: 3000,
+            reactionHandlerEnabled: false,
+            reactionRemoveHandlerEnabled: false,
+            cronEnabled: true,
+            tasksEnabled: false,
+            tasksActive: false,
+            tasksSyncFailureRetryEnabled: true,
+            tasksSyncFailureRetryDelayMs: 30000,
+            tasksSyncDeferredRetryDelayMs: 30000,
+            requireChannelContext: true,
+            autoIndexChannelContext: true,
+        };
+        const base = {
+            metrics,
+            queueDepth: 2,
+            config: baseConfig,
+        };
+        const basic = renderHealthReport({ ...base, mode: 'basic' });
+        expect(basic).toContain('Discoclaw Health');
+        expect(basic).toContain('Queue depth: 2');
+        expect(basic).not.toContain('Config (safe)');
+        const verbose = renderHealthReport({ ...base, mode: 'verbose' });
+        expect(verbose).toContain('Config (safe)');
+        expect(verbose).toContain('runtimeModel=opus');
+        expect(verbose).toContain('Error classes:');
+    });
+    it('shows tasks=active when tasksActive is true', () => {
+        const metrics = new MetricsRegistry();
+        const verbose = renderHealthReport({
+            metrics,
+            queueDepth: 0,
+            config: {
+                runtimeModel: 'opus', runtimeTimeoutMs: 60000, runtimeTools: ['Read'],
+                useRuntimeSessions: true, toolAwareStreaming: false, maxConcurrentInvocations: 0,
+                discordActionsEnabled: false, summaryEnabled: true, durableMemoryEnabled: true,
+                messageHistoryBudget: 3000, reactionHandlerEnabled: false, reactionRemoveHandlerEnabled: false,
+                cronEnabled: true, tasksEnabled: true, tasksActive: true,
+                tasksSyncFailureRetryEnabled: true, tasksSyncFailureRetryDelayMs: 30000, tasksSyncDeferredRetryDelayMs: 30000,
+                requireChannelContext: true, autoIndexChannelContext: true,
+            },
+            mode: 'verbose',
+        });
+        expect(verbose).toContain('tasks=active');
+    });
+    it('shows tasks=degraded when enabled but not active', () => {
+        const metrics = new MetricsRegistry();
+        const verbose = renderHealthReport({
+            metrics,
+            queueDepth: 0,
+            config: {
+                runtimeModel: 'opus', runtimeTimeoutMs: 60000, runtimeTools: ['Read'],
+                useRuntimeSessions: true, toolAwareStreaming: false, maxConcurrentInvocations: 0,
+                discordActionsEnabled: false, summaryEnabled: true, durableMemoryEnabled: true,
+                messageHistoryBudget: 3000, reactionHandlerEnabled: false, reactionRemoveHandlerEnabled: false,
+                cronEnabled: true, tasksEnabled: true, tasksActive: false,
+                tasksSyncFailureRetryEnabled: true, tasksSyncFailureRetryDelayMs: 30000, tasksSyncDeferredRetryDelayMs: 30000,
+                requireChannelContext: true, autoIndexChannelContext: true,
+            },
+            mode: 'verbose',
+        });
+        expect(verbose).toContain('tasks=degraded');
+    });
+    it('shows tasks=off when explicitly disabled', () => {
+        const metrics = new MetricsRegistry();
+        const verbose = renderHealthReport({
+            metrics,
+            queueDepth: 0,
+            config: {
+                runtimeModel: 'opus', runtimeTimeoutMs: 60000, runtimeTools: ['Read'],
+                useRuntimeSessions: true, toolAwareStreaming: false, maxConcurrentInvocations: 0,
+                discordActionsEnabled: false, summaryEnabled: true, durableMemoryEnabled: true,
+                messageHistoryBudget: 3000, reactionHandlerEnabled: false, reactionRemoveHandlerEnabled: false,
+                cronEnabled: true, tasksEnabled: false, tasksActive: false,
+                tasksSyncFailureRetryEnabled: true, tasksSyncFailureRetryDelayMs: 30000, tasksSyncDeferredRetryDelayMs: 30000,
+                requireChannelContext: true, autoIndexChannelContext: true,
+            },
+            mode: 'verbose',
+        });
+        expect(verbose).toContain('tasks=off');
+    });
+    it('shows task sync no-runs message in verbose mode before first sync', () => {
+        const metrics = new MetricsRegistry();
+        const verbose = renderHealthReport({
+            metrics,
+            queueDepth: 0,
+            config: {
+                runtimeModel: 'opus', runtimeTimeoutMs: 60000, runtimeTools: ['Read'],
+                useRuntimeSessions: true, toolAwareStreaming: false, maxConcurrentInvocations: 0,
+                discordActionsEnabled: false, summaryEnabled: true, durableMemoryEnabled: true,
+                messageHistoryBudget: 3000, reactionHandlerEnabled: false, reactionRemoveHandlerEnabled: false,
+                cronEnabled: true, tasksEnabled: true, tasksActive: true,
+                tasksSyncFailureRetryEnabled: true, tasksSyncFailureRetryDelayMs: 30000, tasksSyncDeferredRetryDelayMs: 30000,
+                requireChannelContext: true, autoIndexChannelContext: true,
+            },
+            mode: 'verbose',
+        });
+        expect(verbose).toContain('Task sync: no runs yet');
+    });
+    it('shows task sync lifecycle, transition, and retry metrics in verbose mode', () => {
+        const metrics = new MetricsRegistry();
+        metrics.increment('tasks.sync.started', 4);
+        metrics.increment('tasks.sync.succeeded', 3);
+        metrics.increment('tasks.sync.failed', 1);
+        metrics.increment('tasks.sync.coalesced', 2);
+        metrics.increment('tasks.sync.duration_ms.total', 1100);
+        metrics.increment('tasks.sync.duration_ms.samples', 4);
+        metrics.increment('tasks.sync.transition.threads_created', 5);
+        metrics.increment('tasks.sync.transition.thread_names_updated', 11);
+        metrics.increment('tasks.sync.transition.starter_messages_updated', 12);
+        metrics.increment('tasks.sync.transition.statuses_updated', 13);
+        metrics.increment('tasks.sync.transition.tags_updated', 14);
+        metrics.increment('tasks.sync.transition.threads_archived', 6);
+        metrics.increment('tasks.sync.transition.threads_reconciled', 7);
+        metrics.increment('tasks.sync.transition.orphan_threads_found', 8);
+        metrics.increment('tasks.sync.transition.closes_deferred', 9);
+        metrics.increment('tasks.sync.transition.warnings', 10);
+        metrics.increment('tasks.sync.follow_up.scheduled', 2);
+        metrics.increment('tasks.sync.follow_up.triggered', 2);
+        metrics.increment('tasks.sync.follow_up.succeeded', 1);
+        metrics.increment('tasks.sync.follow_up.failed', 1);
+        metrics.increment('tasks.sync.follow_up.error_class.other', 1);
+        metrics.increment('tasks.sync.retry.scheduled', 3);
+        metrics.increment('tasks.sync.retry.triggered', 2);
+        metrics.increment('tasks.sync.retry.failed', 1);
+        metrics.increment('tasks.sync.retry.coalesced', 5);
+        metrics.increment('tasks.sync.retry.canceled', 2);
+        metrics.increment('tasks.sync.failure_retry.scheduled', 4);
+        metrics.increment('tasks.sync.failure_retry.triggered', 3);
+        metrics.increment('tasks.sync.failure_retry.failed', 2);
+        metrics.increment('tasks.sync.failure_retry.coalesced', 6);
+        metrics.increment('tasks.sync.failure_retry.canceled', 1);
+        metrics.increment('tasks.sync.failure_retry.disabled', 7);
+        metrics.increment('tasks.sync.tag_map_reload.attempted', 9);
+        metrics.increment('tasks.sync.tag_map_reload.succeeded', 8);
+        metrics.increment('tasks.sync.tag_map_reload.failed', 1);
+        const verbose = renderHealthReport({
+            metrics,
+            queueDepth: 0,
+            config: {
+                runtimeModel: 'opus', runtimeTimeoutMs: 60000, runtimeTools: ['Read'],
+                useRuntimeSessions: true, toolAwareStreaming: false, maxConcurrentInvocations: 0,
+                discordActionsEnabled: false, summaryEnabled: true, durableMemoryEnabled: true,
+                messageHistoryBudget: 3000, reactionHandlerEnabled: false, reactionRemoveHandlerEnabled: false,
+                cronEnabled: true, tasksEnabled: true, tasksActive: true,
+                tasksSyncFailureRetryEnabled: false, tasksSyncFailureRetryDelayMs: 12000, tasksSyncDeferredRetryDelayMs: 18000,
+                requireChannelContext: true, autoIndexChannelContext: true,
+            },
+            mode: 'verbose',
+        });
+        expect(verbose).toContain('Task sync: started=4 ok=3 failed=1 coalesced=2 avgMs=275');
+        expect(verbose).toContain('Task sync transitions: created=5 renamed=11 starter=12 statuses=13 tags=14 archived=6 reconciled=7 orphans=8 deferred=9 warnings=10');
+        expect(verbose).toContain('taskSyncPolicy: failureRetry=off failureDelayMs=12000 deferredDelayMs=18000');
+        expect(verbose).toContain('Task sync follow-up/retry: followUp=2/2/1/1 retry=3/2/1 (coalesced=5 canceled=2) failureRetry=4/3/2 (coalesced=6 canceled=1 disabled=7)');
+        expect(verbose).toContain('Task sync tag-map reload: attempts=9 ok=8 failed=1');
+        expect(verbose).toContain('- tasks.sync.follow_up.error_class.other=1');
+    });
+    it('renders tools report', () => {
+        const out = renderHealthToolsReport({
+            permissionTier: 'standard',
+            effectiveTools: ['Read', 'Edit'],
+            configuredRuntimeTools: ['Read', 'Edit', 'WebSearch'],
+        });
+        expect(out).toContain('Discoclaw Tools');
+        expect(out).toContain('Permission tier: standard');
+        expect(out).toContain('Effective tools: Read, Edit');
+        expect(out).toContain('Configured runtime tools: Read, Edit, WebSearch');
+    });
+});

package/dist/discord/help-command.js

@@ -0,0 +1,22 @@
+export function parseHelpCommand(content) {
+    const normalized = String(content ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+    if (normalized !== '!help')
+        return null;
+    return true;
+}
+export function handleHelpCommand() {
+    return [
+        '**Discoclaw commands:**',
+        '',
+        '- `!forge <task>` — start a forge run (AI-drafted + audited plan); `!forge help` for details',
+        '- `!plan <task>` — create and manage phased plans; `!plan help` for details',
+        '- `!memory` — view or edit durable memory; `!memory help` for details',
+        '- `!models` — show or change model assignments; `!models help` for details',
+        '- `!health` — show bot health and metrics; `!health verbose` for full config',
+        '- `!status` — show live runtime status (uptime, crons, memory, API connectivity)',
+        '- `!update` — check for or apply code updates; `!update help` for details',
+        '- `!restart` — restart the discoclaw service; `!restart help` for details',
+        '- `!stop` — abort all active AI streams and cancel any running forge',
+        '- `!help` — this message',
+    ].join('\n');
+}

package/dist/discord/help-command.test.js

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+import { parseHelpCommand, handleHelpCommand } from './help-command.js';
+describe('parseHelpCommand', () => {
+    it('matches !help exactly', () => {
+        expect(parseHelpCommand('!help')).toBe(true);
+    });
+    it('is case-insensitive', () => {
+        expect(parseHelpCommand('!HELP')).toBe(true);
+        expect(parseHelpCommand('!Help')).toBe(true);
+    });
+    it('handles surrounding whitespace', () => {
+        expect(parseHelpCommand('  !help  ')).toBe(true);
+    });
+    it('rejects commands that start with !help but have extra content', () => {
+        expect(parseHelpCommand('!helping')).toBeNull();
+        expect(parseHelpCommand('!helper')).toBeNull();
+        expect(parseHelpCommand('!help me')).toBeNull();
+        expect(parseHelpCommand('!help foo')).toBeNull();
+    });
+    it('returns null for unrelated messages', () => {
+        expect(parseHelpCommand('hello')).toBeNull();
+        expect(parseHelpCommand('!restart')).toBeNull();
+        expect(parseHelpCommand('!health')).toBeNull();
+        expect(parseHelpCommand('')).toBeNull();
+    });
+});
+describe('handleHelpCommand', () => {
+    it('returns a string listing all commands', () => {
+        const result = handleHelpCommand();
+        expect(typeof result).toBe('string');
+        expect(result).toContain('!forge');
+        expect(result).toContain('!plan');
+        expect(result).toContain('!memory');
+        expect(result).toContain('!models');
+        expect(result).toContain('!health');
+        expect(result).toContain('!update');
+        expect(result).toContain('!restart');
+        expect(result).toContain('!stop');
+        expect(result).toContain('!help');
+    });
+    it('mentions help subcommands for commands that have them', () => {
+        const result = handleHelpCommand();
+        expect(result).toContain('!forge help');
+        expect(result).toContain('!plan help');
+        expect(result).toContain('!models help');
+        expect(result).toContain('!update help');
+        expect(result).toContain('!restart help');
+    });
+});

package/dist/discord/image-download.js

@@ -0,0 +1,201 @@
+import { MAX_IMAGES_PER_INVOCATION } from '../runtime/types.js';
+/** Allowed Discord CDN hosts (SSRF protection). */
+const ALLOWED_HOSTS = new Set(['cdn.discordapp.com', 'media.discordapp.net']);
+/** Max bytes per individual image (20 MB). */
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+/** Max total bytes across all images in one message (50 MB). */
+const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+/** Per-image download timeout (10 seconds). */
+const DOWNLOAD_TIMEOUT_MS = 10_000;
+/** Supported image MIME types. */
+const SUPPORTED_MEDIA_TYPES = new Set([
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/gif',
+]);
+/** Extension-to-MIME fallback map. */
+const EXT_TO_MIME = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+    gif: 'image/gif',
+};
+// Per-format minimum payload sizes (structural floors for each format).
+export const MIN_PNG_BYTES = 45; // sig(8) + IHDR(25) + IEND(12)
+export const MIN_JPEG_BYTES = 20; // SOI(2) + marker(4) + frame(11) + EOI(2) ≈ 19, rounded up
+export const MIN_GIF_BYTES = 26; // header(6) + LSD(7) + image desc(10) + LZW(2) + trailer(1)
+export const MIN_WEBP_BYTES = 26; // RIFF(12) + VP8 chunk header(8) + minimal frame(6)
+const MIN_BYTES_FOR_TYPE = {
+    'image/png': MIN_PNG_BYTES,
+    'image/jpeg': MIN_JPEG_BYTES,
+    'image/gif': MIN_GIF_BYTES,
+    'image/webp': MIN_WEBP_BYTES,
+};
+/**
+ * Sniff the image format from magic bytes.
+ * Returns the MIME type string or null if unrecognized.
+ */
+export function sniffMediaType(buffer) {
+    // PNG: 8-byte signature 89 50 4E 47 0D 0A 1A 0A
+    if (buffer.length >= 8 &&
+        buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4E && buffer[3] === 0x47 &&
+        buffer[4] === 0x0D && buffer[5] === 0x0A && buffer[6] === 0x1A && buffer[7] === 0x0A) {
+        return 'image/png';
+    }
+    // JPEG: 3-byte SOI + marker FF D8 FF
+    if (buffer.length >= 3 &&
+        buffer[0] === 0xFF && buffer[1] === 0xD8 && buffer[2] === 0xFF) {
+        return 'image/jpeg';
+    }
+    // GIF: 6-byte version string GIF87a or GIF89a
+    if (buffer.length >= 6 &&
+        buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38 &&
+        (buffer[4] === 0x37 || buffer[4] === 0x39) && buffer[5] === 0x61) {
+        return 'image/gif';
+    }
+    // WebP: RIFF....WEBP (bytes 0-3 = RIFF, bytes 8-11 = WEBP)
+    if (buffer.length >= 12 &&
+        buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46 &&
+        buffer[8] === 0x57 && buffer[9] === 0x45 && buffer[10] === 0x42 && buffer[11] === 0x50) {
+        return 'image/webp';
+    }
+    return null;
+}
+/**
+ * Resolve a Discord attachment's MIME type from its contentType or filename extension.
+ * Returns null if the attachment is not a supported image format.
+ */
+export function resolveMediaType(attachment) {
+    // Prefer Discord's reported contentType.
+    if (attachment.contentType) {
+        const mime = attachment.contentType.split(';')[0].trim().toLowerCase();
+        if (SUPPORTED_MEDIA_TYPES.has(mime))
+            return mime;
+    }
+    // Fall back to file extension.
+    const name = attachment.name ?? '';
+    const dotIdx = name.lastIndexOf('.');
+    if (dotIdx >= 0) {
+        const ext = name.slice(dotIdx + 1).toLowerCase();
+        const mime = EXT_TO_MIME[ext];
+        if (mime)
+            return mime;
+    }
+    return null;
+}
+/** Sanitize an attachment filename for error messages (no URLs or query params). */
+function safeName(attachment) {
+    const raw = attachment.name ?? 'unknown';
+    return raw.replace(/[\x00-\x1f]/g, '').slice(0, 100).trim() || 'unknown';
+}
+/**
+ * Download a single Discord image attachment.
+ * Returns the ImageData on success, or an error string on failure.
+ */
+export async function downloadAttachment(attachment, mediaType) {
+    const name = safeName(attachment);
+    // SSRF protection: validate host.
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(attachment.url);
+    }
+    catch {
+        return { ok: false, error: `${name}: invalid URL` };
+    }
+    if (parsedUrl.protocol !== 'https:' || !ALLOWED_HOSTS.has(parsedUrl.hostname)) {
+        return { ok: false, error: `${name}: blocked (non-Discord CDN host)` };
+    }
+    // Pre-check size from Discord metadata.
+    if (attachment.size != null && attachment.size > MAX_IMAGE_BYTES) {
+        const sizeMB = (attachment.size / (1024 * 1024)).toFixed(1);
+        return { ok: false, error: `${name}: too large (${sizeMB} MB, max 20 MB)` };
+    }
+    try {
+        const response = await fetch(attachment.url, {
+            signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+            redirect: 'error',
+        });
+        if (!response.ok) {
+            return { ok: false, error: `${name}: HTTP ${response.status}` };
+        }
+        const buffer = Buffer.from(await response.arrayBuffer());
+        // Post-download size check.
+        if (buffer.length > MAX_IMAGE_BYTES) {
+            const sizeMB = (buffer.length / (1024 * 1024)).toFixed(1);
+            return { ok: false, error: `${name}: too large (${sizeMB} MB, max 20 MB)` };
+        }
+        // Sniff actual format from magic bytes — override declared MIME.
+        const sniffed = sniffMediaType(buffer);
+        if (!sniffed) {
+            return { ok: false, error: `${name}: unsupported image format (magic bytes don't match PNG, JPEG, GIF, or WebP)` };
+        }
+        // Reject truncated payloads below format structural minimums.
+        const minBytes = MIN_BYTES_FOR_TYPE[sniffed];
+        if (minBytes && buffer.length < minBytes) {
+            return { ok: false, error: `${name}: image too small to be valid ${sniffed} (${buffer.length} bytes, minimum ${minBytes})` };
+        }
+        return {
+            ok: true,
+            image: {
+                base64: buffer.toString('base64'),
+                mediaType: sniffed,
+            },
+        };
+    }
+    catch (err) {
+        const errObj = err instanceof Error ? err : null;
+        if (errObj?.name === 'TimeoutError' || errObj?.name === 'AbortError') {
+            return { ok: false, error: `${name}: download timed out` };
+        }
+        if (errObj?.name === 'TypeError' && String(errObj.message).includes('redirect')) {
+            return { ok: false, error: `${name}: blocked (unexpected redirect)` };
+        }
+        return { ok: false, error: `${name}: download failed` };
+    }
+}
+/**
+ * Download image attachments from a Discord message.
+ *
+ * Filters for supported image types, respects MAX_IMAGES_PER_INVOCATION,
+ * and enforces a total byte cap across all images.
+ */
+export async function downloadMessageImages(attachments, maxImages = MAX_IMAGES_PER_INVOCATION) {
+    // Filter to supported image attachments with resolved MIME types.
+    const candidates = [];
+    for (const att of attachments) {
+        const mediaType = resolveMediaType(att);
+        if (mediaType)
+            candidates.push({ attachment: att, mediaType });
+    }
+    // Cap at maxImages.
+    const toDownload = candidates.slice(0, maxImages);
+    if (toDownload.length === 0)
+        return { images: [], errors: [] };
+    // Pre-check total byte budget from Discord metadata.
+    let estimatedTotal = 0;
+    const withinBudget = [];
+    const errors = [];
+    for (const item of toDownload) {
+        const size = item.attachment.size ?? 0;
+        if (estimatedTotal + size > MAX_TOTAL_BYTES) {
+            errors.push(`${safeName(item.attachment)}: skipped (total size limit exceeded)`);
+            continue;
+        }
+        estimatedTotal += size;
+        withinBudget.push(item);
+    }
+    // Download all in parallel.
+    const results = await Promise.all(withinBudget.map(({ attachment, mediaType }) => downloadAttachment(attachment, mediaType)));
+    const images = [];
+    for (const result of results) {
+        if (result.ok) {
+            images.push(result.image);
+        }
+        else {
+            errors.push(result.error);
+        }
+    }
+    return { images, errors };
+}