discoclaw 0.1.0

package/dist/discord/message-coordinator.onboarding.test.js

@@ -0,0 +1,183 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createMessageCreateHandler } from './message-coordinator.js';
+import { completeOnboarding } from './onboarding-completion.js';
+import { getDefaultTimezone } from '../cron/default-timezone.js';
+vi.mock('../workspace-bootstrap.js', () => ({
+    isOnboardingComplete: vi.fn(async () => false),
+}));
+vi.mock('./onboarding-completion.js', () => ({
+    completeOnboarding: vi.fn(async () => ({
+        writeResult: { written: ['IDENTITY.md', 'USER.md'], errors: [], warnings: [] },
+    })),
+}));
+vi.mock('../cron/default-timezone.js', () => ({
+    getDefaultTimezone: vi.fn(() => 'Etc/Test'),
+}));
+function makeParams(workspaceCwd) {
+    const metrics = { increment: vi.fn() };
+    const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+    return {
+        allowUserIds: new Set(['user-1']),
+        dataDir: workspaceCwd,
+        botDisplayName: 'Discoclaw',
+        requireChannelContext: false,
+        autoIndexChannelContext: false,
+        autoJoinThreads: false,
+        useRuntimeSessions: false,
+        runtime: { id: 'claude', capabilities: {} },
+        sessionManager: {},
+        workspaceCwd,
+        projectCwd: workspaceCwd,
+        groupsDir: workspaceCwd,
+        useGroupDirCwd: false,
+        runtimeModel: 'capable',
+        runtimeTools: [],
+        runtimeTimeoutMs: 30_000,
+        discordActionsEnabled: false,
+        discordActionsChannels: false,
+        discordActionsMessaging: false,
+        discordActionsGuild: false,
+        discordActionsModeration: false,
+        discordActionsPolls: false,
+        messageHistoryBudget: 0,
+        summaryEnabled: false,
+        summaryModel: 'fast',
+        summaryMaxChars: 2000,
+        summaryEveryNTurns: 6,
+        summaryDataDir: workspaceCwd,
+        durableMemoryEnabled: false,
+        durableDataDir: workspaceCwd,
+        durableInjectMaxChars: 2000,
+        durableMaxItems: 100,
+        memoryCommandsEnabled: false,
+        planCommandsEnabled: false,
+        forgeCommandsEnabled: false,
+        summaryToDurableEnabled: false,
+        shortTermMemoryEnabled: false,
+        shortTermDataDir: workspaceCwd,
+        shortTermMaxEntries: 0,
+        shortTermMaxAgeMs: 0,
+        shortTermInjectMaxChars: 0,
+        streamStallWarningMs: 10_000,
+        actionFollowupDepth: 1,
+        reactionHandlerEnabled: false,
+        reactionRemoveHandlerEnabled: false,
+        reactionMaxAgeMs: 0,
+        healthCommandsEnabled: false,
+        metrics,
+        log,
+    };
+}
+function makeMessage(overrides = {}) {
+    const author = {
+        id: 'user-1',
+        bot: false,
+        displayName: 'Alice',
+        username: 'alice',
+        send: vi.fn(async () => ({})),
+    };
+    const channel = {
+        id: 'dm-1',
+        name: 'dm',
+        send: vi.fn(async () => ({})),
+        isThread: () => false,
+    };
+    const msg = {
+        id: 'm1',
+        type: 0,
+        content: 'hello',
+        author,
+        guildId: null,
+        guild: null,
+        channelId: 'dm-1',
+        channel,
+        client: { channels: { cache: new Map() }, user: { id: 'bot-1' } },
+        attachments: new Map(),
+        stickers: new Map(),
+        embeds: [],
+        mentions: { has: () => false },
+        reply: vi.fn(async () => ({})),
+    };
+    return Object.assign(msg, overrides);
+}
+describe('message coordinator onboarding', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date('2026-02-21T08:00:00.000Z'));
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('completes onboarding with defaults when an active session is timed out', async () => {
+        const workspaceCwd = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-onboard-timeout-'));
+        await fs.writeFile(path.join(workspaceCwd, 'IDENTITY.md'), 'template marker', 'utf8');
+        const params = makeParams(workspaceCwd);
+        const queue = { run: vi.fn(async () => undefined) };
+        const handler = createMessageCreateHandler(params, queue);
+        const startMsg = makeMessage();
+        await handler(startMsg);
+        vi.setSystemTime(new Date('2026-02-22T08:00:01.000Z'));
+        const timedOutMsg = makeMessage({
+            id: 'm2',
+            author: startMsg.author,
+            channel: startMsg.channel,
+            content: 'still here',
+        });
+        await handler(timedOutMsg);
+        expect(queue.run).not.toHaveBeenCalled();
+        expect(vi.mocked(getDefaultTimezone)).toHaveBeenCalled();
+        expect(vi.mocked(completeOnboarding)).toHaveBeenCalledTimes(1);
+        expect(vi.mocked(completeOnboarding)).toHaveBeenCalledWith({ userName: 'Alice', timezone: 'Etc/Test', morningCheckin: false }, workspaceCwd, startMsg.author, undefined);
+    });
+    it('sends redirect once for wrong-channel onboarding messages and then passes through', async () => {
+        const workspaceCwd = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-onboard-redirect-'));
+        await fs.writeFile(path.join(workspaceCwd, 'IDENTITY.md'), 'template marker', 'utf8');
+        const params = makeParams(workspaceCwd);
+        const queue = { run: vi.fn(async () => undefined) };
+        const handler = createMessageCreateHandler(params, queue);
+        const startMsg = makeMessage();
+        await handler(startMsg);
+        const wrongChannelMsg1 = makeMessage({
+            id: 'm2',
+            author: startMsg.author,
+            content: 'hello from guild',
+            guildId: 'guild-1',
+            guild: { id: 'guild-1' },
+            channelId: 'guild-channel-1',
+            channel: {
+                id: 'guild-channel-1',
+                name: 'general',
+                send: vi.fn(async () => ({})),
+                isThread: () => false,
+            },
+        });
+        await handler(wrongChannelMsg1);
+        expect(wrongChannelMsg1.reply).toHaveBeenCalledTimes(1);
+        expect(wrongChannelMsg1.reply).toHaveBeenCalledWith(expect.objectContaining({
+            content: expect.stringContaining('setting things up with you in DMs'),
+        }));
+        expect(queue.run).toHaveBeenCalledTimes(1);
+        const wrongChannelMsg2 = makeMessage({
+            id: 'm3',
+            author: startMsg.author,
+            content: 'another guild message',
+            guildId: 'guild-1',
+            guild: { id: 'guild-1' },
+            channelId: 'guild-channel-2',
+            channel: {
+                id: 'guild-channel-2',
+                name: 'general-2',
+                send: vi.fn(async () => ({})),
+                isThread: () => false,
+            },
+        });
+        await handler(wrongChannelMsg2);
+        expect(wrongChannelMsg2.reply).not.toHaveBeenCalled();
+        expect(queue.run).toHaveBeenCalledTimes(2);
+        expect(vi.mocked(completeOnboarding)).not.toHaveBeenCalled();
+    });
+});

package/dist/discord/message-coordinator.plan-run.test.js

@@ -0,0 +1,264 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+vi.mock('../workspace-bootstrap.js', () => ({
+    isOnboardingComplete: vi.fn(async () => true),
+}));
+vi.mock('./plan-commands.js', () => ({
+    parsePlanCommand: vi.fn((content) => {
+        const trimmed = content.trim();
+        if (!trimmed.startsWith('!plan run '))
+            return null;
+        return { action: 'run', args: trimmed.slice('!plan run '.length) };
+    }),
+    handlePlanCommand: vi.fn(async () => 'ok'),
+    preparePlanRun: vi.fn(async () => ({
+        phasesFilePath: '/tmp/plans/plan-042-phases.md',
+        planFilePath: '/tmp/plans/plan-042-test.md',
+        planContent: '# Plan',
+        nextPhase: { id: 'phase-1', title: 'First phase', kind: 'implement', status: 'pending', deps: [], contextFiles: [] },
+    })),
+    handlePlanSkip: vi.fn(async () => 'ok'),
+    closePlanIfComplete: vi.fn(async () => ({ closed: false, reason: 'not_all_complete' })),
+    NO_PHASES_SENTINEL: 'NO_PHASES',
+    findPlanFile: vi.fn(async () => null),
+    looksLikePlanId: vi.fn(() => false),
+}));
+vi.mock('./plan-manager.js', () => ({
+    runNextPhase: vi.fn(async () => ({ result: 'nothing_to_run' })),
+    resolveProjectCwd: vi.fn((_content, workspaceCwd) => workspaceCwd),
+    readPhasesFile: vi.fn(() => ({ phases: [] })),
+    buildPostRunSummary: vi.fn(() => ''),
+}));
+vi.mock('./forge-plan-registry.js', () => ({
+    acquireWriterLock: vi.fn(async () => vi.fn()),
+    setActiveOrchestrator: vi.fn(),
+    getActiveOrchestrator: vi.fn(() => null),
+    addRunningPlan: vi.fn(),
+    removeRunningPlan: vi.fn(),
+    isPlanRunning: vi.fn(() => false),
+}));
+function makeParams() {
+    const metrics = { increment: vi.fn() };
+    const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+    return {
+        allowUserIds: new Set(['user-1']),
+        botDisplayName: 'Discoclaw',
+        requireChannelContext: false,
+        autoIndexChannelContext: false,
+        autoJoinThreads: false,
+        useRuntimeSessions: false,
+        runtime: { id: 'claude', capabilities: {} },
+        sessionManager: {},
+        workspaceCwd: '/tmp/workspace',
+        projectCwd: '/tmp/workspace',
+        groupsDir: '/tmp/workspace',
+        useGroupDirCwd: false,
+        runtimeModel: 'capable',
+        runtimeTools: [],
+        runtimeTimeoutMs: 30_000,
+        discordActionsEnabled: false,
+        discordActionsChannels: false,
+        discordActionsMessaging: false,
+        discordActionsGuild: false,
+        discordActionsModeration: false,
+        discordActionsPolls: false,
+        messageHistoryBudget: 0,
+        summaryEnabled: false,
+        summaryModel: 'fast',
+        summaryMaxChars: 2000,
+        summaryEveryNTurns: 6,
+        summaryDataDir: '/tmp/workspace',
+        durableMemoryEnabled: false,
+        durableDataDir: '/tmp/workspace',
+        durableInjectMaxChars: 2000,
+        durableMaxItems: 100,
+        memoryCommandsEnabled: false,
+        planCommandsEnabled: true,
+        planPhasesEnabled: true,
+        planPhaseMaxContextFiles: 5,
+        forgeCommandsEnabled: false,
+        summaryToDurableEnabled: false,
+        shortTermMemoryEnabled: false,
+        shortTermDataDir: '/tmp/workspace',
+        shortTermMaxEntries: 0,
+        shortTermMaxAgeMs: 0,
+        shortTermInjectMaxChars: 0,
+        streamStallWarningMs: 10_000,
+        actionFollowupDepth: 1,
+        reactionHandlerEnabled: false,
+        reactionRemoveHandlerEnabled: false,
+        reactionMaxAgeMs: 0,
+        healthCommandsEnabled: false,
+        metrics,
+        log,
+    };
+}
+function makeMessage(content) {
+    const phaseMsg = {
+        edit: vi.fn(async () => ({})),
+    };
+    const progressReply = {
+        edit: vi.fn(async () => ({})),
+    };
+    const channel = {
+        id: 'channel-1',
+        name: 'general',
+        send: vi.fn(async () => phaseMsg),
+        isThread: () => false,
+    };
+    return {
+        id: 'm1',
+        type: 0,
+        content,
+        author: { id: 'user-1', bot: false },
+        guildId: 'g1',
+        guild: { id: 'g1' },
+        channelId: 'channel-1',
+        channel,
+        client: { channels: { cache: new Map() }, user: { id: 'bot-1' } },
+        attachments: new Map(),
+        stickers: new Map(),
+        embeds: [],
+        mentions: { has: () => false },
+        reply: vi.fn(async () => progressReply),
+        progressReply,
+        phaseMsg,
+    };
+}
+async function makeHandler(params, queue) {
+    const { createMessageCreateHandler } = await import('./message-coordinator.js');
+    return createMessageCreateHandler(params, queue);
+}
+describe('message coordinator plan run phase-start posts', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('posts phase-start updates for manual !plan run with non phase-* ids', async () => {
+        const { runNextPhase } = await import('./plan-manager.js');
+        runNextPhase.mockImplementationOnce(async (_phases, _plan, opts) => {
+            await opts.onPlanEvent?.({
+                type: 'phase_start',
+                planId: 'plan-042',
+                phase: { id: 'audit-1', title: 'Post implementation audit', kind: 'audit' },
+            });
+            return { result: 'nothing_to_run' };
+        });
+        const queue = { run: vi.fn(async (_key, fn) => fn()) };
+        const handler = await makeHandler(makeParams(), queue);
+        const msg = makeMessage('!plan run plan-042');
+        await handler(msg);
+        await vi.waitFor(() => {
+            expect(runNextPhase).toHaveBeenCalled();
+            expect(msg.channel.send).toHaveBeenCalledWith(expect.objectContaining({
+                content: '**Post implementation audit**...',
+            }));
+        });
+    });
+    it('deduplicates repeated phase-start progress lines in a single run', async () => {
+        const { runNextPhase } = await import('./plan-manager.js');
+        runNextPhase.mockImplementationOnce(async (_phases, _plan, opts) => {
+            const event = {
+                type: 'phase_start',
+                planId: 'plan-042',
+                phase: { id: 'phase-1', title: 'First phase', kind: 'implement' },
+            };
+            await opts.onPlanEvent?.(event);
+            await opts.onPlanEvent?.(event);
+            return { result: 'nothing_to_run' };
+        });
+        const queue = { run: vi.fn(async (_key, fn) => fn()) };
+        const handler = await makeHandler(makeParams(), queue);
+        const msg = makeMessage('!plan run plan-042');
+        await handler(msg);
+        await vi.waitFor(() => {
+            const phaseStartPosts = msg.channel.send.mock.calls
+                .map((call) => String(call[0]?.content ?? ''))
+                .filter((content) => content.includes('**First phase**...'));
+            expect(phaseStartPosts).toHaveLength(1);
+        });
+    });
+    it('edits phase-start message to resolved state on phase_complete (done)', async () => {
+        const { runNextPhase } = await import('./plan-manager.js');
+        runNextPhase.mockImplementationOnce(async (_phases, _plan, opts) => {
+            await opts.onPlanEvent?.({
+                type: 'phase_start',
+                planId: 'plan-042',
+                phase: { id: 'phase-1', title: 'First phase', kind: 'implement' },
+            });
+            await opts.onPlanEvent?.({
+                type: 'phase_complete',
+                planId: 'plan-042',
+                phase: { id: 'phase-1', title: 'First phase', kind: 'implement' },
+                status: 'done',
+            });
+            return { result: 'nothing_to_run' };
+        });
+        const queue = { run: vi.fn(async (_key, fn) => fn()) };
+        const handler = await makeHandler(makeParams(), queue);
+        const msg = makeMessage('!plan run plan-042');
+        await handler(msg);
+        await vi.waitFor(() => {
+            expect(msg.channel.send).toHaveBeenCalledWith(expect.objectContaining({
+                content: '**First phase**...',
+            }));
+            expect(msg.phaseMsg.edit).toHaveBeenCalledWith(expect.objectContaining({
+                content: '[x] **First phase**',
+            }));
+        });
+    });
+    it('edits phase-start message with failure indicator on phase_complete (failed)', async () => {
+        const { runNextPhase } = await import('./plan-manager.js');
+        runNextPhase.mockImplementationOnce(async (_phases, _plan, opts) => {
+            await opts.onPlanEvent?.({
+                type: 'phase_start',
+                planId: 'plan-042',
+                phase: { id: 'phase-1', title: 'First phase', kind: 'implement' },
+            });
+            await opts.onPlanEvent?.({
+                type: 'phase_complete',
+                planId: 'plan-042',
+                phase: { id: 'phase-1', title: 'First phase', kind: 'implement' },
+                status: 'failed',
+            });
+            return { result: 'nothing_to_run' };
+        });
+        const queue = { run: vi.fn(async (_key, fn) => fn()) };
+        const handler = await makeHandler(makeParams(), queue);
+        const msg = makeMessage('!plan run plan-042');
+        await handler(msg);
+        await vi.waitFor(() => {
+            expect(msg.phaseMsg.edit).toHaveBeenCalledWith(expect.objectContaining({
+                content: '[!] **First phase**',
+            }));
+        });
+    });
+    it('posts a final summary channel message after a full plan run', async () => {
+        const { runNextPhase } = await import('./plan-manager.js');
+        runNextPhase
+            .mockImplementationOnce(async (_phases, _plan, opts) => {
+            await opts.onPlanEvent?.({
+                type: 'phase_start',
+                planId: 'plan-042',
+                phase: { id: 'phase-1', title: 'First phase', kind: 'implement' },
+            });
+            return {
+                result: 'done',
+                phase: { id: 'phase-1', title: 'First phase', kind: 'implement', status: 'done', dependsOn: [], contextFiles: [] },
+                output: 'done',
+                nextPhase: undefined,
+            };
+        })
+            .mockImplementationOnce(async () => ({ result: 'nothing_to_run' }));
+        const queue = { run: vi.fn(async (_key, fn) => fn()) };
+        const handler = await makeHandler(makeParams(), queue);
+        const msg = makeMessage('!plan run plan-042');
+        await handler(msg);
+        await vi.waitFor(() => {
+            // The final channel.send should include a plan-run-complete summary
+            const finalSend = msg.channel.send.mock.calls.find((call) => {
+                const content = String(call[0]?.content ?? '');
+                return content.includes('plan-042') && content.includes('phase');
+            });
+            expect(finalSend).toBeDefined();
+        });
+    });
+});

package/dist/discord/message-history.js

@@ -0,0 +1,53 @@
+/**
+ * Fetch recent messages from a Discord channel and format them as conversation
+ * history suitable for prepending to a prompt.
+ *
+ * Returns an empty string if no history is available or on any fetch error.
+ */
+export async function fetchMessageHistory(channel, beforeMessageId, opts) {
+    if (opts.budgetChars <= 0)
+        return '';
+    let messages;
+    try {
+        messages = await channel.messages.fetch({
+            before: beforeMessageId,
+            limit: opts.fetchLimit ?? 10,
+        });
+    }
+    catch {
+        return '';
+    }
+    if (!messages || messages.size === 0)
+        return '';
+    // Discord API returns newest-first; convert to array and reverse to chronological order.
+    const sorted = [...messages.values()].reverse();
+    // Build history from most recent backward so the most relevant context is kept.
+    let remaining = opts.budgetChars;
+    const selected = [];
+    for (let i = sorted.length - 1; i >= 0 && remaining > 0; i--) {
+        const m = sorted[i];
+        const author = m.author.bot ? (opts.botDisplayName ?? 'Discoclaw') : (m.author.displayName || m.author.username);
+        const content = String(m.content ?? '');
+        const full = `[${author}]: ${content}`;
+        if (m.author.bot && full.length > remaining) {
+            // Truncate bot messages to fit remaining budget.
+            const prefix = `[${author}]: `;
+            const maxContent = Math.max(0, remaining - prefix.length - 3);
+            if (maxContent <= 0)
+                break;
+            selected.unshift(`${prefix}${content.slice(0, maxContent)}...`);
+            remaining = 0;
+        }
+        else if (full.length > remaining) {
+            // User message doesn't fit — stop.
+            break;
+        }
+        else {
+            selected.unshift(full);
+            remaining -= full.length + 1; // +1 for newline separator
+        }
+    }
+    if (selected.length === 0)
+        return '';
+    return selected.join('\n');
+}

package/dist/discord/message-history.test.js

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+import { fetchMessageHistory } from './message-history.js';
+/** Helper: create a fake Discord message. */
+function fakeMsg(id, content, username, bot = false) {
+    return {
+        id,
+        content,
+        author: { username, displayName: username, bot },
+    };
+}
+/** Helper: create a fake channel whose messages.fetch returns the given messages (newest-first). */
+function fakeChannel(messages) {
+    return {
+        messages: {
+            fetch: async () => {
+                // Discord returns a Collection (Map-like) with newest-first order.
+                const map = new Map();
+                for (const m of messages)
+                    map.set(m.id, m);
+                return map;
+            },
+        },
+    };
+}
+describe('fetchMessageHistory', () => {
+    it('fetches and formats messages in chronological order', async () => {
+        const ch = fakeChannel([
+            fakeMsg('3', 'sounds good', 'TestUser'),
+            fakeMsg('2', 'Before I create it, let me confirm...', 'Discoclaw', true),
+            fakeMsg('1', 'create a status channel', 'TestUser'),
+        ]);
+        const result = await fetchMessageHistory(ch, '4', { budgetChars: 5000 });
+        const lines = result.split('\n');
+        expect(lines).toHaveLength(3);
+        expect(lines[0]).toBe('[TestUser]: create a status channel');
+        expect(lines[1]).toBe('[Discoclaw]: Before I create it, let me confirm...');
+        expect(lines[2]).toBe('[TestUser]: sounds good');
+    });
+    it('respects char budget — stops adding messages when full', async () => {
+        const ch = fakeChannel([
+            fakeMsg('3', 'c', 'User'),
+            fakeMsg('2', 'b', 'User'),
+            fakeMsg('1', 'aaaaaaaaaa', 'User'), // oldest — long enough to exceed budget
+        ]);
+        // Budget enough for the two recent short messages but not all three.
+        // "[User]: c" = 9 chars, "[User]: b" = 9 chars, + 1 newline = 19 chars
+        const result = await fetchMessageHistory(ch, '4', { budgetChars: 19 });
+        const lines = result.split('\n');
+        expect(lines).toHaveLength(2);
+        expect(lines[0]).toBe('[User]: b');
+        expect(lines[1]).toBe('[User]: c');
+    });
+    it('truncates bot responses that exceed remaining budget', async () => {
+        const longResponse = 'A'.repeat(200);
+        const ch = fakeChannel([
+            fakeMsg('2', longResponse, 'Discoclaw', true),
+            fakeMsg('1', 'hi', 'User'),
+        ]);
+        // Budget enough for part of the bot response but not all.
+        const result = await fetchMessageHistory(ch, '3', { budgetChars: 50 });
+        expect(result).toContain('[Discoclaw]:');
+        expect(result).toContain('...');
+        expect(result.length).toBeLessThanOrEqual(55); // some tolerance for formatting
+    });
+    it('includes user messages in full', async () => {
+        const ch = fakeChannel([
+            fakeMsg('2', 'this is a user message', 'Alice'),
+            fakeMsg('1', 'hello', 'Alice'),
+        ]);
+        const result = await fetchMessageHistory(ch, '3', { budgetChars: 5000 });
+        expect(result).toContain('[Alice]: hello');
+        expect(result).toContain('[Alice]: this is a user message');
+    });
+    it('handles fetch failures gracefully (returns empty string)', async () => {
+        const ch = {
+            messages: {
+                fetch: async () => { throw new Error('forbidden'); },
+            },
+        };
+        const result = await fetchMessageHistory(ch, '1', { budgetChars: 3000 });
+        expect(result).toBe('');
+    });
+    it('returns empty string when no prior messages exist', async () => {
+        const ch = fakeChannel([]);
+        const result = await fetchMessageHistory(ch, '1', { budgetChars: 3000 });
+        expect(result).toBe('');
+    });
+    it('returns empty string when budget is 0', async () => {
+        const ch = fakeChannel([
+            fakeMsg('1', 'hello', 'User'),
+        ]);
+        const result = await fetchMessageHistory(ch, '2', { budgetChars: 0 });
+        expect(result).toBe('');
+    });
+});

package/dist/discord/models-command.js

@@ -0,0 +1,59 @@
+import { executeConfigAction } from './actions-config.js';
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+const VALID_ROLES = new Set(['chat', 'fast', 'forge-drafter', 'forge-auditor', 'summary', 'cron', 'cron-exec']);
+export function parseModelsCommand(content) {
+    const tokens = String(content ?? '').trim().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return null;
+    if (tokens[0].toLowerCase() !== '!models')
+        return null;
+    if (tokens.length === 1)
+        return { action: 'show' };
+    const subcommand = tokens[1].toLowerCase();
+    if (subcommand === 'show' && tokens.length === 2)
+        return { action: 'show' };
+    if (subcommand === 'help' && tokens.length === 2)
+        return { action: 'help' };
+    if (subcommand !== 'set' || tokens.length !== 4)
+        return null;
+    const role = tokens[2].toLowerCase();
+    if (!VALID_ROLES.has(role))
+        return null;
+    // Preserve original case for model IDs.
+    return { action: 'set', role: role, model: tokens[3] };
+}
+export function handleModelsCommand(cmd, opts) {
+    const { configCtx, configEnabled } = opts;
+    if (!configCtx) {
+        return configEnabled
+            ? 'Model configuration is not yet available — the bot is still starting up. Try again in a moment.'
+            : 'Model configuration is disabled.';
+    }
+    if (cmd.action === 'help') {
+        return [
+            '**!models commands:**',
+            '- `!models` — show current model assignments for all roles',
+            '- `!models show` — same as above',
+            '- `!models set <role> <model>` — change the model for a role at runtime',
+            '- `!models help` — this message',
+            '',
+            '**Roles:** `chat`, `fast`, `forge-drafter`, `forge-auditor`, `summary`, `cron`, `cron-exec`',
+            '',
+            '**Examples:**',
+            '- `!models set chat sonnet`',
+            '- `!models set fast haiku`',
+            '- `!models set forge-drafter opus`',
+            '- `!models set cron-exec haiku` — run crons on a cheaper model',
+            '- `!models set cron-exec default` — revert to following chat model',
+        ].join('\n');
+    }
+    if (cmd.action === 'show') {
+        const result = executeConfigAction({ type: 'modelShow' }, configCtx);
+        return result.ok ? result.summary : `Error: ${result.error}`;
+    }
+    // action === 'set'
+    const result = executeConfigAction({ type: 'modelSet', role: cmd.role, model: cmd.model }, configCtx);
+    return result.ok ? result.summary : `Error: ${result.error}`;
+}