chatroom-cli 1.31.1 → 1.32.1

package/dist/commands/get-next-task/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Get Next Task Command — entry point.
+ *
+ * Handles all pre-flight validation (auth, chatroom access, participant join,
+ * init prompt) and then delegates to `GetNextTaskSession.start()`.
+ */
+export type { SessionParams, GetNextTaskResponse } from './session.js';
+export { GetNextTaskSession } from './session.js';
+interface GetNextTaskOptions {
+    role: string;
+    silent?: boolean;
+}
+/**
+ * Get next task from a chatroom.
+ *
+ * Handles all pre-flight validation (auth, chatroom access, participant join,
+ * init prompt) and then delegates to `GetNextTaskSession.start()`.
+ */
+export declare function getNextTask(chatroomId: string, options: GetNextTaskOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/get-next-task/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/get-next-task/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIlD,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAID;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+JhG"}

package/dist/commands/get-next-task/index.js

@@ -0,0 +1,156 @@
+/**
+ * Get Next Task Command — entry point.
+ *
+ * Handles all pre-flight validation (auth, chatroom access, participant join,
+ * init prompt) and then delegates to `GetNextTaskSession.start()`.
+ */
+import { getNextTaskGuidance } from '@workspace/backend/prompts/cli/index.js';
+import { getCliEnvPrefix } from '@workspace/backend/prompts/utils/env.js';
+import { GetNextTaskSession } from './session.js';
+import { api } from '../../api.js';
+import { getOtherSessionUrls, getSessionId } from '../../infrastructure/auth/storage.js';
+import { getConvexClient, getConvexUrl } from '../../infrastructure/convex/client.js';
+import { formatConnectivityError, isNetworkError } from '../../utils/error-formatting.js';
+export { GetNextTaskSession } from './session.js';
+// ─── Entry Point ────────────────────────────────────────────────────────────
+/**
+ * Get next task from a chatroom.
+ *
+ * Handles all pre-flight validation (auth, chatroom access, participant join,
+ * init prompt) and then delegates to `GetNextTaskSession.start()`.
+ */
+export async function getNextTask(chatroomId, options) {
+    const client = await getConvexClient();
+    const { role, silent } = options;
+    // Get Convex URL and CLI env prefix for generating commands
+    const convexUrl = getConvexUrl();
+    const cliEnvPrefix = getCliEnvPrefix(convexUrl);
+    // Get session ID for authentication
+    const sessionId = getSessionId();
+    if (!sessionId) {
+        const otherUrls = getOtherSessionUrls();
+        console.error(`❌ Not authenticated for: ${convexUrl}`);
+        if (otherUrls.length > 0) {
+            console.error(`\n💡 You have sessions for other environments:`);
+            for (const url of otherUrls) {
+                console.error(`   • ${url}`);
+            }
+            console.error(`\n   To use a different environment, set CHATROOM_CONVEX_URL:`);
+            console.error(`   CHATROOM_CONVEX_URL=${otherUrls[0]} chatroom get-next-task ...`);
+            console.error(`\n   Or to authenticate for the current environment:`);
+        }
+        console.error(`   chatroom auth login`);
+        process.exit(1);
+    }
+    // Validate chatroom ID format before query
+    if (!chatroomId ||
+        typeof chatroomId !== 'string' ||
+        chatroomId.length < 20 ||
+        chatroomId.length > 40) {
+        console.error(`❌ Invalid chatroom ID format: ID must be 20-40 characters (got ${chatroomId?.length || 0})`);
+        process.exit(1);
+    }
+    if (!/^[a-zA-Z0-9_]+$/.test(chatroomId)) {
+        console.error(`❌ Invalid chatroom ID format: ID must contain only alphanumeric characters and underscores`);
+        process.exit(1);
+    }
+    // Validate chatroom exists and user has access
+    let chatroom;
+    try {
+        chatroom = await client.query(api.chatrooms.get, {
+            sessionId,
+            chatroomId: chatroomId,
+        });
+    }
+    catch (error) {
+        if (isNetworkError(error)) {
+            formatConnectivityError(error, convexUrl);
+            process.exit(1);
+        }
+        throw error;
+    }
+    if (!chatroom) {
+        console.error(`❌ Chatroom ${chatroomId} not found or access denied`);
+        process.exit(1);
+    }
+    // Generate a unique connection ID for this get-next-task session
+    const connectionId = `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    // Determine agent type ('custom' | 'remote') from team agent config
+    let participantAgentType;
+    try {
+        const teamConfigs = await client.query(api.machines.getTeamAgentConfigs, {
+            sessionId,
+            chatroomId: chatroomId,
+        });
+        const roleConfig = teamConfigs?.find((c) => c.role.toLowerCase() === role.toLowerCase());
+        participantAgentType = roleConfig?.type;
+    }
+    catch {
+        // Non-critical — continue without agent type
+    }
+    // Register presence in the chatroom before starting the subscription.
+    // NOTE: action is intentionally NOT set to 'get-next-task:started' here.
+    // The 'get-next-task:started' action (which emits agent.waiting and marks the agent
+    // as "waiting" for queue-promotion purposes) is sent AFTER the WebSocket subscription
+    // is established in GetNextTaskSession.subscribe(). This ensures tasks are only
+    // acknowledged after the agent is truly ready to receive them.
+    await client.mutation(api.participants.join, {
+        sessionId,
+        chatroomId: chatroomId,
+        role,
+        action: 'get-next-task:connecting',
+        connectionId,
+        agentType: participantAgentType,
+    });
+    // Log initial connection with timestamp
+    const connectionTime = new Date().toISOString().replace('T', ' ').substring(0, 19);
+    if (!silent) {
+        console.log(`[${connectionTime}] ⏳ Connecting to chatroom as "${role}"...`);
+    }
+    // On first session, fetch and display the full initialization prompt from backend
+    try {
+        const initPromptResult = await client.query(api.messages.getInitPrompt, {
+            sessionId,
+            chatroomId: chatroomId,
+            role,
+            convexUrl,
+        });
+        if (initPromptResult?.prompt) {
+            const connectedTime = new Date().toISOString().replace('T', ' ').substring(0, 19);
+            console.log(`[${connectedTime}] ✅ Connected. Waiting for task...\n`);
+            console.log(`⚠️ IMPORTANT: This command must stay in the FOREGROUND. If moved to background, terminate and restart it — background processes cannot deliver tasks.\n`);
+            if (!initPromptResult.hasSystemPromptControl) {
+                console.log('<!-- REFERENCE: Agent Initialization');
+                console.log('');
+                console.log('═'.repeat(50));
+                console.log('📋 AGENT INITIALIZATION PROMPT');
+                console.log('═'.repeat(50));
+                console.log('');
+                console.log(getNextTaskGuidance());
+                console.log('');
+                console.log('═'.repeat(50));
+                console.log('');
+                console.log(initPromptResult.prompt);
+                console.log('');
+                console.log('═'.repeat(50));
+                console.log('-->');
+                console.log('');
+            }
+        }
+    }
+    catch {
+        // Fallback - init prompt not critical, continue without it
+    }
+    // --- Delegate to the session class ---
+    const session = new GetNextTaskSession({
+        chatroomId,
+        role,
+        silent: !!silent,
+        sessionId,
+        connectionId,
+        cliEnvPrefix,
+        client,
+    });
+    await session.start();
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/get-next-task/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/get-next-task/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/get-next-task/index.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * get-next-task index Unit Tests
+ *
+ * Tests that `get-next-task` does NOT call `updateAgentConfig`.
+ * Agent harness configuration is now owned exclusively by `startAgent`/daemon,
+ * not by the per-task `get-next-task` command.
+ */
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/commands/get-next-task/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../../src/commands/get-next-task/index.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/commands/get-next-task/index.test.js

@@ -0,0 +1,125 @@
+/**
+ * get-next-task index Unit Tests
+ *
+ * Tests that `get-next-task` does NOT call `updateAgentConfig`.
+ * Agent harness configuration is now owned exclusively by `startAgent`/daemon,
+ * not by the per-task `get-next-task` command.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+// ---------------------------------------------------------------------------
+// Mock infrastructure modules
+// ---------------------------------------------------------------------------
+const mockMutation = vi.fn();
+const mockQuery = vi.fn();
+vi.mock('../../infrastructure/convex/client.js', () => ({
+    getConvexUrl: () => 'http://127.0.0.1:3210',
+    getConvexClient: vi.fn().mockResolvedValue({
+        mutation: mockMutation,
+        query: mockQuery,
+    }),
+    getConvexWsClient: vi.fn(),
+}));
+vi.mock('../../infrastructure/auth/storage.js', () => ({
+    getSessionId: vi.fn().mockReturnValue('test-session-id'),
+    getOtherSessionUrls: vi.fn().mockReturnValue([]),
+}));
+vi.mock('./session.js', () => ({
+    GetNextTaskSession: class {
+        start = vi.fn().mockResolvedValue(undefined);
+    },
+}));
+vi.mock('../../api.js', () => ({
+    api: {
+        machines: {
+            register: 'machines:register',
+            updateAgentConfig: 'machines:updateAgentConfig',
+            getTeamAgentConfigs: 'machines:getTeamAgentConfigs',
+        },
+        chatrooms: {
+            get: 'chatrooms:get',
+        },
+        participants: {
+            join: 'participants:join',
+            getByRole: 'participants:getByRole',
+        },
+        messages: {
+            getTaskDeliveryPrompt: 'messages:getTaskDeliveryPrompt',
+            getInitPrompt: 'messages:getInitPrompt',
+        },
+    },
+}));
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const TEST_CHATROOM_ID = 'jx750h696te75x67z5q6cbwkph7zvm2x';
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('get-next-task — agent config ownership', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // Happy-path query responses
+        mockQuery.mockImplementation(async (queryFn) => {
+            if (queryFn === 'chatrooms:get') {
+                return {
+                    _id: TEST_CHATROOM_ID,
+                    teamName: 'Test Team',
+                    teamRoles: ['builder', 'reviewer'],
+                    teamEntryPoint: 'builder',
+                };
+            }
+            if (queryFn === 'participants:getByRole') {
+                return { role: 'builder', chatroomId: TEST_CHATROOM_ID };
+            }
+            if (queryFn === 'machines:getTeamAgentConfigs') {
+                return [];
+            }
+            return undefined;
+        });
+        mockMutation.mockResolvedValue({ success: true });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('prints foreground warning after connecting when not silent', async () => {
+        const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        mockQuery.mockImplementation(async (queryFn) => {
+            if (queryFn === 'chatrooms:get') {
+                return {
+                    _id: TEST_CHATROOM_ID,
+                    teamName: 'Test',
+                    teamRoles: ['builder'],
+                    teamEntryPoint: 'builder',
+                };
+            }
+            if (queryFn === 'machines:getTeamAgentConfigs')
+                return [];
+            if (queryFn === 'messages:getInitPrompt') {
+                return { prompt: 'init prompt text', hasSystemPromptControl: true };
+            }
+            return undefined;
+        });
+        const { getNextTask } = await import('./index.js');
+        await getNextTask(TEST_CHATROOM_ID, { role: 'builder' }).catch(() => { });
+        const allOutput = consoleSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+        expect(allOutput).toContain('FOREGROUND');
+        expect(allOutput).toContain('background');
+        expect(allOutput).toContain('terminate and restart');
+        consoleSpy.mockRestore();
+    });
+    it('should NEVER call updateAgentConfig — agent config is owned by startAgent, not get-next-task', async () => {
+        // Agent harness configuration (agentType, workingDir) is now written exclusively
+        // by the startAgent/daemon flow. get-next-task only registers the machine presence
+        // (machines:register) and joins the participant — it does NOT touch agentType config.
+        const { getNextTask } = await import('./index.js');
+        await getNextTask(TEST_CHATROOM_ID, {
+            role: 'builder',
+            silent: true,
+        }).catch(() => {
+            // Session errors are expected and irrelevant to this assertion
+        });
+        const updateAgentConfigCalls = mockMutation.mock.calls.filter(([fn]) => fn === 'machines:updateAgentConfig');
+        expect(updateAgentConfigCalls.length, 'updateAgentConfig must never be called from get-next-task').toBe(0);
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/commands/get-next-task/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../../src/commands/get-next-task/index.test.ts"],"names":[],"mappings":"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"}

package/dist/commands/get-next-task/session.d.ts

@@ -0,0 +1,127 @@
+/**
+ * GetNextTaskSession — encapsulates the subscription lifecycle for getting next tasks.
+ *
+ * Every event handler funnels through `logAndExit()` to guarantee the process
+ * exits with proper logging, event identification, and reconnection guidance.
+ */
+import { type BackendErrorCode } from '@workspace/backend/config/errorCodes.js';
+import type { SessionId } from 'convex-helpers/server/sessions';
+import { type Id } from '../../api.js';
+import type { getConvexClient } from '../../infrastructure/convex/client.js';
+/** Discriminated union response from `getPendingTasksForRole` subscription. */
+export type GetNextTaskResponse = {
+    type: 'tasks';
+    tasks: {
+        task: {
+            _id: Id<'chatroom_tasks'>;
+            status: string;
+        };
+        message: {
+            _id: Id<'chatroom_messages'>;
+        } | null;
+    }[];
+} | {
+    type: 'no_tasks';
+} | {
+    type: 'grace_period';
+    taskId: string;
+    remainingMs: number;
+} | {
+    type: 'superseded';
+    newConnectionId: string;
+} | {
+    type: 'reconnect';
+    reason: string;
+} | {
+    type: 'error';
+    code: BackendErrorCode;
+    message: string;
+    fatal: boolean;
+};
+/** Parameters passed from the preflight phase to the session. */
+export interface SessionParams {
+    chatroomId: string;
+    role: string;
+    silent: boolean;
+    sessionId: SessionId;
+    connectionId: string;
+    cliEnvPrefix: string;
+    client: Awaited<ReturnType<typeof getConvexClient>>;
+}
+/**
+ * Encapsulates the subscription lifecycle for getting next tasks.
+ *
+ * State that was previously scattered as loose `let` variables in the function
+ * scope is now held as private instance fields, making the guarantees around
+ * cleanup, deduplication, and process exit explicit and auditable.
+ */
+export declare class GetNextTaskSession {
+    private unsubscribe;
+    private cleanedUp;
+    private taskProcessed;
+    private fatalExitTriggered;
+    private readonly chatroomId;
+    private readonly role;
+    private readonly silent;
+    private readonly sessionId;
+    private readonly connectionId;
+    private readonly cliEnvPrefix;
+    private readonly client;
+    constructor(params: SessionParams);
+    /** Start the subscription and signal handlers. */
+    start(): Promise<void>;
+    /**
+     * Cornerstone exit method — every handler funnels through here.
+     *
+     * 1. Logs the event type received.
+     * 2. Logs the descriptive message.
+     * 3. Logs reconnection guidance (the `getNextTaskCommand(...)` output).
+     * 4. Fire-and-forget `cleanup()`, then synchronous `process.exit(exitCode)`.
+     *
+     * Return type is `never` — `process.exit()` is synchronous and truly never returns.
+     */
+    private logAndExit;
+    /**
+     * Cleanup helper — call on EVERY exit path.
+     * Unsubscribes from the task subscription and tells the backend this participant has left.
+     * Safe to call multiple times (idempotent).
+     */
+    private cleanup;
+    private subscribe;
+    /** Handle the discriminated union response from subscription. */
+    private handleSubscriptionResponse;
+    /**
+     * Another process has taken over this role's connection.
+     * Exit gracefully so the old agent process terminates cleanly.
+     */
+    private handleSuperseded;
+    /**
+     * Task is in grace period — another agent may still be working on it.
+     * Exit with guidance to reconnect.
+     */
+    private handleGracePeriod;
+    /**
+     * Backend requested a reconnect.
+     * Exit with the reason and reconnection guidance.
+     */
+    private handleReconnect;
+    /**
+     * Error event from the subscription.
+     * Fatal errors exit with code 1; non-fatal errors exit with code 0.
+     */
+    private handleError;
+    /**
+     * Handle errors from WebSocket subscription callbacks.
+     * - ConvexError with a fatal code → logAndExit(1)
+     * - ConvexError with a non-fatal code → logAndExit(0)
+     * - Non-ConvexError (network, transient) → logAndExit(0)
+     */
+    private handleSubscriptionError;
+    /**
+     * Process received tasks — claim, deliver, and exit.
+     * Exit 0 on success, exit 1 on delivery failure.
+     */
+    private handleTasks;
+    private registerSignalHandlers;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/commands/get-next-task/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/commands/get-next-task/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,gBAAgB,EAEtB,MAAM,yCAAyC,CAAC;AAGjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEhE,OAAO,EAAO,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAS7E,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAC3B;IACE,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE;QACL,IAAI,EAAE;YAAE,GAAG,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QACpD,OAAO,EAAE;YAAE,GAAG,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAA;SAAE,GAAG,IAAI,CAAC;KAClD,EAAE,CAAC;CACL,GACD;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/E,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC;CACrD;AAMD;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAE7B,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,kBAAkB,CAAS;IAGnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAErC,MAAM,EAAE,aAAa;IAcjC,kDAAkD;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;;;;;;;;OASG;IACH,OAAO,CAAC,UAAU;IAmClB;;;;OAIG;YACW,OAAO;YAmCP,SAAS;IAyCvB,iEAAiE;YACnD,0BAA0B;IA+BxC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACH,OAAO,CAAC,eAAe;IASvB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAoBnB;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAgC/B;;;OAGG;YACW,WAAW;IAkFzB,OAAO,CAAC,sBAAsB;CAe/B"}