@gkorepanov/ccodex 0.4.20 → 0.4.24

package/dist/claude/service.js

@@ -7,8 +7,9 @@ import { SqliteHybridStore } from "../store/sqliteStore.js";
 import { LayeredHybridStore } from "../store/memoryStore.js";
 import { createClaudeQuery } from "./queryFactory.js";
 import { claudeEnvironment } from "./environment.js";
-import { invalidParams } from "../protocol/errors.js";
-import { paginateTurns, turnCursor } from "../protocol/turnPagination.js";
+import { invalidParams, invalidRequest } from "../protocol/errors.js";
+import { historyCursors, paginateItems, paginateTurns, startedTurn } from "../protocol/turnPagination.js";
+import { searchTurnOccurrences, threadSearchSnippet } from "../protocol/search.js";
 import { MetricsRegistry } from "../observability/metrics.js";
 import { SdkTranscriptBrancher, } from "./transcriptBrancher.js";
 import { ClaudeRateLimitCoordinator, } from "./rateLimits.js";
@@ -257,6 +258,8 @@ export class ClaudeService {
     nativeSessionCatalog;
     ephemeralReleases = new Map();
     ephemeralReleaseTimers = new Map();
+    /** Root threads whose last turn completed or failed and whose queue drains once the session is quiescent. */
+    queueDrainPending = new Set();
     removalRetries = new Map();
     terminalAdmins = new Map();
     settingsUpdates = new Map();
@@ -292,7 +295,7 @@ export class ClaudeService {
         const sessionRepository = new ClaudeSessionRepository(this.store);
         this.sessionOutput = new ClaudeOutputAdapter(hub);
         this.rateLimits = new ClaudeRateLimitCoordinator(logger);
-        this.sessions = new ClaudeSessionRegistry((threadId) => new ClaudeSession(threadId, sessionRepository, this.sessionOutput, undefined, metrics, undefined, (childThreadId) => this.sessions.registerChild(childThreadId, threadId), (childThreadId) => this.sessions.unregisterChild(childThreadId), shellRunner, undefined, {
+        this.sessions = new ClaudeSessionRegistry((threadId) => new ClaudeSession(threadId, sessionRepository, this.sessionOutput, undefined, metrics, (update) => this.onSessionLifecycle(threadId, update), (childThreadId) => this.sessions.registerChild(childThreadId, threadId), (childThreadId) => this.sessions.unregisterChild(childThreadId), shellRunner, undefined, {
             claudeBinary: this.config.claudeBinary,
             logger: this.logger,
             queryFactory: this.queryFactory,
@@ -301,7 +304,7 @@ export class ClaudeService {
             invalidateModelCatalog: () => this.modelCatalog?.invalidate?.(),
             ...(this.skillsChanged ? { skillsChanged: this.skillsChanged } : {}),
             isClosing: () => this.closing,
-            persistUserSideSessions: this.config.features?.sideChatPromotion ?? true,
+            persistUserSideSessions: true,
             interactiveQuestions: this.config.features?.interactiveQuestions ?? true,
             resolveChildModel: (model) => {
                 const value = normalizeClaudeModelIdentifier(model);
@@ -548,10 +551,10 @@ export class ClaudeService {
             throw invalidParams(`Unknown Claude thread '${threadId}'.`);
         if (record.thread.parentThreadId) {
             record = this.withCatalogModel(record);
+            record = { ...record, thread: this.withNativeMetadata(record) };
             return {
                 ...threadResponse(record, !resume.excludeTurns),
-                turnsBackwardsCursor: record.thread.turns.length ? turnCursor(record.thread.turns.at(-1).id, true) : null,
-                itemsBackwardsCursor: record.thread.turns.some((turn) => turn.items.length) ? "hyb-item:0" : null,
+                ...historyCursors(record.thread.turns),
                 initialTurnsPage: resume.initialTurnsPage
                     ? this.turnsPage({
                         threadId,
@@ -575,10 +578,12 @@ export class ClaudeService {
         await (await this.sessions.getOrCreate(threadId)).materializeRuntime();
         record = await this.sessions.submit(threadId, { type: "readThread", includeTurns: true });
         record = this.withCatalogModel(record);
+        record = { ...record, thread: this.withNativeMetadata(record) };
+        if (this.store.listQueuedSubmissions(threadId).length)
+            this.scheduleQueueDrain(threadId);
         return {
             ...threadResponse(record, !resume.excludeTurns),
-            turnsBackwardsCursor: record.thread.turns.length ? turnCursor(record.thread.turns.at(-1).id, true) : null,
-            itemsBackwardsCursor: record.thread.turns.some((turn) => turn.items.length) ? "hyb-item:0" : null,
+            ...historyCursors(record.thread.turns),
             initialTurnsPage: resume.initialTurnsPage
                 ? this.turnsPage({
                     threadId,
@@ -629,6 +634,10 @@ export class ClaudeService {
     }
     async prepareTurn(params, review) {
         this.requireIndependentThread(params.threadId, "start a turn in");
+        if (params.toolOutput)
+            throw invalidParams("Claude threads do not support toolOutput.");
+        if (params.serviceTierForTurn != null)
+            this.logger.warn("claude.turn.service-tier-for-turn.ignored", { threadId: params.threadId, serviceTierForTurn: params.serviceTierForTurn });
         const availability = await this.availabilityProbe();
         if (availability.state !== "ready")
             throw invalidParams(providerUnavailableMessage(availability));
@@ -655,7 +664,8 @@ export class ClaudeService {
             let announcement;
             const startAndWait = () => announcement ? announcement.then(startRuntime) : startRuntime();
             return {
-                response: { turn: prepared.turn },
+                response: { turn: startedTurn(prepared.turn) },
+                turn: prepared.turn,
                 announce: () => announcement ??= this.sessions.submit(params.threadId, { type: "announceTurn", turnId: prepared.turn.id }),
                 start: () => {
                     void startAndWait().catch((error) => this.logger.error("claude.turn.start-failed", { threadId: params.threadId, error: String(error) }));
@@ -891,7 +901,10 @@ export class ClaudeService {
     }
     async shellCommand(params) {
         this.requireIndependentThread(params.threadId, "run a shell command in");
-        await this.sessions.submit(params.threadId, { type: "runShell", command: params.command });
+        const timeoutMs = params.timeoutMs ?? 3_600_000;
+        if (timeoutMs < 0)
+            throw invalidParams(`thread/shellCommand timeoutMs must be non-negative, got ${timeoutMs}`);
+        await this.sessions.submit(params.threadId, { type: "runShell", command: params.command, timeoutMs });
         return {};
     }
     async prepareReview(params) {
@@ -914,6 +927,8 @@ export class ClaudeService {
         let reviewThreadId = params.threadId;
         let forkedThread;
         if (params.delivery === "detached") {
+            if (this.requireRecord(params.threadId, false).thread.historyMode === "paginated")
+                throw invalidRequest("paginated threads do not support detached review");
             const fork = await this.forkThread({ threadId: params.threadId, excludeTurns: false });
             reviewThreadId = fork.thread.id;
             forkedThread = fork.thread;
@@ -923,7 +938,7 @@ export class ClaudeService {
                 threadId: reviewThreadId,
                 input: [{ type: "text", text: prompt, text_elements: [] }],
             }, { label: review, display: review });
-            const userItem = prepared.response.turn.items.find((item) => item.type === "userMessage");
+            const userItem = prepared.turn.items.find((item) => item.type === "userMessage");
             return {
                 response: {
                     turn: {
@@ -982,6 +997,15 @@ export class ClaudeService {
         this.nativeMetadataRead = read;
         return read;
     }
+    async setGeneratedThreadName(params, userPrompt) {
+        const record = this.requireRecord(params.threadId, false);
+        if (record.thread.parentThreadId || this.nativeMetadata.get(record.claudeSessionId)?.customTitle)
+            return;
+        await this.sessions.submit(params.threadId, {
+            type: "threadAdmin",
+            command: { kind: "generatedName", name: params.name, userPrompt },
+        });
+    }
     async setThreadName(params) {
         const record = this.requireRecord(params.threadId, false);
         if (record.thread.parentThreadId) {
@@ -1086,7 +1110,7 @@ export class ClaudeService {
         if (this.closing || this.ephemeralReleaseTimers.has(threadId))
             return;
         const record = this.store.getThreadRecord(threadId, false);
-        if (!record?.thread.ephemeral || record.thread.parentThreadId)
+        if (!record?.thread.ephemeral || record.thread.parentThreadId || record.thread.threadSource === "user")
             return;
         const timer = setTimeout(() => {
             this.ephemeralReleaseTimers.delete(threadId);
@@ -1125,63 +1149,28 @@ export class ClaudeService {
     }
     listItems(params) {
         this.assertThreadAvailable(params.threadId);
-        const items = this.store.listTurns(params.threadId)
-            .flatMap((turn) => params.turnId && turn.id !== params.turnId
-            ? []
-            : turn.items.map((item) => ({ turnId: turn.id, item })));
-        const ordered = params.sortDirection === "desc" ? [...items].reverse() : items;
-        if (params.cursor && !params.cursor.startsWith("hyb-item:"))
-            throw invalidParams("Invalid Claude item cursor.");
-        const offset = params.cursor?.startsWith("hyb-item:") ? Number(params.cursor.slice("hyb-item:".length)) : 0;
-        if (!Number.isInteger(offset) || offset < 0)
-            throw invalidParams("Invalid Claude item cursor.");
-        const limit = Math.max(1, Math.min(params.limit ?? 50, 100));
-        const data = ordered.slice(offset, offset + limit);
-        return {
-            data,
-            nextCursor: offset + data.length < ordered.length ? `hyb-item:${offset + data.length}` : null,
-            backwardsCursor: data.length > 0 ? `hyb-item:${Math.max(0, offset - limit)}` : null,
-        };
+        return paginateItems(this.store.listTurns(params.threadId), params, ["hyb-item:"]);
     }
     searchOccurrences(params) {
         this.assertThreadAvailable(params.threadId);
+        return searchTurnOccurrences(params.threadId, this.store.listTurns(params.threadId), params);
+    }
+    /** `thread/search` over durable Claude threads: one result per thread with the first matching snippet. */
+    searchThreads(params) {
         const searchTerm = params.searchTerm.trim();
-        if (!searchTerm)
-            throw invalidParams("thread/searchOccurrences requires a non-empty searchTerm.");
-        if (params.cursor && !params.cursor.startsWith("hyb-search:"))
-            throw invalidParams("Invalid Claude search cursor.");
-        const offset = params.cursor ? Number(params.cursor.slice("hyb-search:".length)) : 0;
-        if (!Number.isInteger(offset) || offset < 0)
-            throw invalidParams("Invalid Claude search cursor.");
-        const turns = this.store.listTurns(params.threadId);
-        const needle = searchTerm.toLocaleLowerCase();
-        const occurrences = turns.flatMap((turn) => turn.items.flatMap((item) => {
-            const text = item.type === "userMessage"
-                ? item.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("\n")
-                : item.type === "agentMessage" && item.phase !== "commentary" ? item.text : undefined;
-            if (text === undefined)
+        return this.listThreads({ archived: params.archived ?? false }).flatMap((thread) => {
+            if (thread.ephemeral)
                 return [];
-            const haystack = text.toLocaleLowerCase();
-            const matches = [];
-            for (let start = haystack.indexOf(needle); start >= 0; start = haystack.indexOf(needle, start + needle.length)) {
-                matches.push({
-                    turnId: turn.id,
-                    itemId: item.id,
-                    snippet: text,
-                    snippetMatchRange: { start, end: start + needle.length },
-                    turnCursor: turnCursor(turn.id, true),
-                });
-            }
-            return matches;
-        }));
-        const limit = Math.max(1, Math.min(params.limit ?? 50, 100));
-        const data = occurrences.slice(offset, offset + limit);
-        return {
-            data,
-            nextCursor: offset + data.length < occurrences.length ? `hyb-search:${offset + data.length}` : null,
-        };
+            const snippet = threadSearchSnippet(this.store.listTurns(thread.id), searchTerm);
+            return snippet === undefined ? [] : [{ thread: { ...thread, turns: [] }, snippet }];
+        });
     }
-    async forkThread(params, visibleForkedFromId = params.threadId) {
+    async forkThread(params, visibleForkedFromId = params.threadId, reservedSideId) {
+        if (reservedSideId && this.store.hasThread(reservedSideId)) {
+            const session = await this.sessions.getOrCreate(reservedSideId);
+            await session.ensureEphemeralRuntime();
+            return threadResponse(this.requireRecord(reservedSideId, false), false);
+        }
         if (params.path)
             throw invalidParams("Claude thread forks must use threadId, not a Codex rollout path.");
         this.requireIndependentThread(params.threadId, "fork");
@@ -1194,6 +1183,8 @@ export class ClaudeService {
             : undefined;
         const source = await this.sessions.submit(params.threadId, { type: "snapshotBranch" });
         const sourceRecord = source.record;
+        if (sourceRecord.thread.historyMode === "paginated" && params.ephemeral && !params.excludeTurns)
+            throw invalidRequest("ephemeral paginated thread/fork requires `excludeTurns: true`");
         const sidePromotion = Boolean((this.config.features?.sideChatPromotion ?? true)
             && sourceRecord.thread.ephemeral
             && sourceRecord.thread.threadSource === "user"
@@ -1271,12 +1262,13 @@ export class ClaudeService {
             cwd: sourceRecord.thread.cwd,
             runtimeWorkspaceRoots: storedWorkspaceRoots(sourceRecord),
         });
-        const threadId = uuidv7();
+        const threadId = reservedSideId ?? uuidv7();
         const thread = {
             ...sourceRecord.thread, id: threadId, ephemeral: params.ephemeral ?? false,
             section: null, sectionEnteredAt: null, projectId: null,
             sessionId: threadId, forkedFromId: visibleForkedFromId,
-            cwd, modelProvider: "claude", createdAt, updatedAt: createdAt, recencyAt: createdAt,
+            cwd, modelProvider: "claude", model: modelPickerId, reasoningEffort,
+            createdAt, updatedAt: createdAt, recencyAt: createdAt,
             status: params.ephemeral ? { type: "idle" } : { type: "notLoaded" },
             canAcceptDirectInput: true,
             name: params.ephemeral
@@ -1336,6 +1328,8 @@ export class ClaudeService {
     }
     async rollbackThread(params) {
         const source = await this.truncationSource(params.threadId, "roll back");
+        if (source.record.thread.historyMode === "paginated")
+            throw invalidRequest("paginated threads do not support thread/rollback");
         if (!Number.isInteger(params.numTurns) || params.numTurns < 1)
             throw invalidParams("numTurns must be at least 1.");
         if (params.numTurns > source.record.thread.turns.length)
@@ -1352,8 +1346,7 @@ export class ClaudeService {
         const retained = (await this.truncateThread(source, keepCount)).thread;
         return {
             thread: { ...retained, turns: [] },
-            turnsBackwardsCursor: retained.turns.length ? turnCursor(retained.turns.at(-1).id, true) : null,
-            itemsBackwardsCursor: retained.turns.some((turn) => turn.items.length) ? "hyb-item:0" : null,
+            ...historyCursors(retained.turns),
         };
     }
     async truncationSource(threadId, verb) {
@@ -1399,6 +1392,106 @@ export class ClaudeService {
         this.requireIndependentThread(params.threadId, "set a goal on");
         return this.sessions.submit(params.threadId, { type: "goal", command: { kind: "prepareSet", params } }).then((mutation) => this.goalHandle(params.threadId, mutation));
     }
+    async addQueuedSubmission(params) {
+        this.requireIndependentThread(params.threadId, "queue a submission in");
+        const queuedSubmission = await this.sessions.submit(params.threadId, {
+            type: "queue",
+            command: { kind: "add", input: params.input, clientUserMessageId: params.clientUserMessageId },
+        });
+        return { response: { queuedSubmission }, after: () => this.drainQueue(params.threadId) };
+    }
+    /** Offset pagination over the durable per-thread queue; the cursor is the base-10 offset, as in stock. */
+    listQueue(params) {
+        this.requireRecord(params.threadId, false);
+        const cursor = params.cursor ?? null;
+        if (cursor !== null && !/^\d+$/u.test(cursor))
+            throw invalidRequest(`invalid queue pagination cursor: ${cursor}`);
+        const offset = cursor === null ? 0 : Number(cursor);
+        const limit = Math.min(Math.max(params.limit ?? 25, 1), 100);
+        const queue = this.store.listQueuedSubmissions(params.threadId);
+        return {
+            data: queue.slice(offset, offset + limit),
+            nextCursor: offset + limit < queue.length ? String(offset + limit) : null,
+        };
+    }
+    async updateQueuedSubmission(params) {
+        this.requireIndependentThread(params.threadId, "update a queued submission in");
+        const queuedSubmission = await this.sessions.submit(params.threadId, {
+            type: "queue",
+            command: { kind: "update", queuedSubmissionId: params.queuedSubmissionId, input: params.input },
+        });
+        return { queuedSubmission };
+    }
+    async deleteQueuedSubmission(params) {
+        this.requireIndependentThread(params.threadId, "delete a queued submission from");
+        const deleted = await this.sessions.submit(params.threadId, {
+            type: "queue", command: { kind: "delete", queuedSubmissionId: params.queuedSubmissionId },
+        });
+        return { deleted };
+    }
+    async reorderQueue(params) {
+        this.requireIndependentThread(params.threadId, "reorder the queue of");
+        await this.sessions.submit(params.threadId, {
+            type: "queue", command: { kind: "reorder", queuedSubmissionIds: params.queuedSubmissionIds },
+        });
+        return {};
+    }
+    async prepareQueueStart(params) {
+        this.requireIndependentThread(params.threadId, "start a queued submission in");
+        const entry = await this.sessions.submit(params.threadId, {
+            type: "queue",
+            command: {
+                kind: "take",
+                manual: true,
+                ...(params.queuedSubmissionId == null ? {} : { queuedSubmissionId: params.queuedSubmissionId }),
+            },
+        });
+        return this.startQueuedSubmission(params.threadId, entry);
+    }
+    async startQueuedSubmission(threadId, entry) {
+        try {
+            return await this.prepareTurn({ threadId, input: entry.input, clientUserMessageId: entry.clientUserMessageId });
+        }
+        catch (error) {
+            await this.sessions.submit(threadId, { type: "queue", command: { kind: "restore", entry } });
+            throw error;
+        }
+    }
+    /** Starts the head of the queue when the thread is idle and its last turn was not interrupted. */
+    async drainQueue(threadId) {
+        if (this.closing || this.store.listQueuedSubmissions(threadId).length === 0)
+            return;
+        const entry = await this.sessions.submit(threadId, {
+            type: "queue", command: { kind: "take", manual: false },
+        });
+        if (!entry)
+            return;
+        let prepared;
+        try {
+            prepared = await this.startQueuedSubmission(threadId, entry);
+        }
+        catch (error) {
+            this.logger[error instanceof ActiveClaudeTurnError ? "info" : "warn"]("claude.queue.drain-skipped", {
+                threadId, queuedSubmissionId: entry.id, error: String(error),
+            });
+            return;
+        }
+        await prepared.announce();
+        prepared.start();
+    }
+    scheduleQueueDrain(threadId) {
+        queueMicrotask(() => {
+            void this.drainQueue(threadId).catch((error) => {
+                this.logger.warn("claude.queue.drain-failed", { threadId, error: String(error) });
+            });
+        });
+    }
+    onSessionLifecycle(threadId, update) {
+        if (update.completed && update.completed.turn.status !== "interrupted")
+            this.queueDrainPending.add(threadId);
+        if (update.quiescent && this.queueDrainPending.delete(threadId))
+            this.scheduleQueueDrain(threadId);
+    }
     async getGoal(threadId) {
         if (this.requireRecord(threadId, false).thread.parentThreadId)
             return { goal: null };
@@ -1708,6 +1801,10 @@ export class ClaudeService {
         return record;
     }
     withNativeMetadata(record) {
+        if (record.thread.ephemeral && record.thread.threadSource === "user"
+            && !record.thread.parentThreadId && record.thread.status.type === "notLoaded") {
+            record = { ...record, thread: { ...record.thread, status: { type: "idle" } } };
+        }
         const native = this.nativeMetadata.get(record.claudeSessionId);
         if (!native)
             return {
@@ -1807,8 +1904,8 @@ export class ClaudeService {
                 section: null,
                 sectionEnteredAt: null,
                 projectId: null,
-                historyMode: params.historyMode ?? "legacy",
-                modelProvider: "claude",
+                historyMode: params.historyMode ?? (params.ephemeral ? "legacy" : "paginated"),
+                modelProvider: "claude", model: modelPickerId, reasoningEffort,
                 createdAt,
                 updatedAt: createdAt,
                 recencyAt: createdAt,