@jait/gateway 0.1.377 → 0.1.379

package/dist/tools/thread-tools.js

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { extractTodoResultItems } from "../providers/todo-result.js";
 import { GitService, cleanupWorktreeRemoteAware } from "../services/git.js";
 import { resolveThreadSelectionDefaults } from "../services/thread-defaults.js";
@@ -27,6 +28,21 @@ function normalizeThreadProviderId(value) {
             return null;
     }
 }
+function normalizePrompt(message, prompt) {
+    const value = typeof prompt === "string" && prompt.trim() ? prompt : message;
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+function normalizeTimeoutMs(timeoutMinutes, defaultMinutes) {
+    const minutes = typeof timeoutMinutes === "number" && Number.isFinite(timeoutMinutes)
+        ? timeoutMinutes
+        : defaultMinutes;
+    if (minutes === undefined || minutes <= 0)
+        return undefined;
+    return Math.max(1, Math.floor(minutes * 60_000));
+}
 export function createThreadControlTool(deps) {
     const gitService = deps.gitService ?? new GitService();
     const broadcastThreadEvent = (threadId, event, data) => {
@@ -43,6 +59,38 @@ export function createThreadControlTool(deps) {
         const userId = context.userId?.trim();
         return userId || "system";
     };
+    const createManagedDeliveryWorktree = async (thread) => {
+        if (thread.kind !== "delivery")
+            return thread;
+        if (thread.branch)
+            return thread;
+        const cwd = thread.workingDirectory?.trim();
+        if (!cwd)
+            return thread;
+        if (!existsSync(cwd))
+            return thread;
+        if (!gitService.isRepo || !gitService.createWorktree)
+            return thread;
+        const isRepo = await gitService.isRepo(cwd).catch(() => false);
+        if (!isRepo)
+            return thread;
+        let remoteUrl = null;
+        if (gitService.getPreferredRemote && gitService.getRemoteUrl) {
+            const remote = await gitService.getPreferredRemote(cwd).catch(() => null);
+            if (remote) {
+                remoteUrl = await gitService.getRemoteUrl(cwd, remote).catch(() => null);
+            }
+        }
+        const defaultBranch = gitService.resolveDefaultBranch
+            ? await gitService.resolveDefaultBranch(cwd, remoteUrl).catch(() => "main")
+            : "main";
+        const branch = `jait/${thread.id.slice(-8)}`;
+        const worktree = await gitService.createWorktree(cwd, defaultBranch, branch);
+        return deps.threadService.update(thread.id, {
+            workingDirectory: worktree.path,
+            branch: worktree.branch,
+        }) ?? thread;
+    };
     const resolveSelectedThreadDefaults = (context) => {
         const defaults = resolveThreadSelectionDefaults({
             userId: context.userId,
@@ -95,17 +143,23 @@ export function createThreadControlTool(deps) {
             return undefined;
         return thread;
     };
-    const startThread = async (context, thread, message, attachments) => {
+    const startThread = async (context, thread, options = {}) => {
+        const message = normalizePrompt(options.message);
         if (thread.status === "running" && thread.providerSessionId) {
             return { ok: false, message: "Thread is already running" };
         }
+        if (!message) {
+            return { ok: false, message: "start requires non-empty `prompt`." };
+        }
         const resolvedProvider = resolveStoredThreadProvider(thread.providerId, context);
         if (!resolvedProvider.providerId) {
             return { ok: false, message: resolvedProvider.error ?? "Unable to resolve a provider for this thread." };
         }
         const effectiveProviderId = resolvedProvider.providerId;
         const effectiveThread = thread;
-        const autoFinishAfterFirstTurn = effectiveThread.kind === "delegation" && typeof message === "string" && message.trim().length > 0;
+        const autoFinishAfterFirstTurn = effectiveThread.kind === "delegation" || options.autoStopAfterTurn === true;
+        const detach = options.detach === true || context.requestedBy === "scheduler";
+        const timeoutMs = normalizeTimeoutMs(options.timeoutMinutes, context.requestedBy === "scheduler" ? 240 : undefined);
         const provider = deps.providerRegistry.get(effectiveProviderId);
         if (!provider) {
             return { ok: false, message: `Provider '${effectiveProviderId}' not found` };
@@ -125,7 +179,20 @@ export function createThreadControlTool(deps) {
                 model: effectiveThread.model ?? context.model ?? undefined,
                 mcpServers,
             });
-            const unsubscribe = provider.onEvent((event) => {
+            let timeout;
+            let unsubscribed = false;
+            let unsubscribe;
+            const cleanup = () => {
+                if (timeout) {
+                    clearTimeout(timeout);
+                    timeout = undefined;
+                }
+                if (unsubscribe && !unsubscribed) {
+                    unsubscribed = true;
+                    unsubscribe();
+                }
+            };
+            unsubscribe = provider.onEvent((event) => {
                 if (event.sessionId !== session.id) {
                     return;
                 }
@@ -149,12 +216,12 @@ export function createThreadControlTool(deps) {
                         deps.threadService.markCompleted(effectiveThread.id);
                     }
                     broadcastThreadEvent(effectiveThread.id, "status", { status: "completed" });
-                    unsubscribe();
+                    cleanup();
                 }
                 else if (event.type === "session.error") {
                     deps.threadService.markError(effectiveThread.id, event.error);
                     broadcastThreadEvent(effectiveThread.id, "status", { status: "error", error: event.error });
-                    unsubscribe();
+                    cleanup();
                 }
                 else if (event.type === "turn.started") {
                     // Re-assert running when a new turn begins
@@ -164,43 +231,77 @@ export function createThreadControlTool(deps) {
                         broadcastThreadEvent(effectiveThread.id, "status", { status: "running" });
                     }
                 }
-                else if (event.type === "turn.completed" && autoFinishAfterFirstTurn) {
-                    void provider.stopSession(session.id).catch(() => {
-                        // Best effort: delegation threads should not linger if the provider
-                        // leaves the session open after answering the first task.
-                    });
-                    deps.threadService.markCompletedAndClearSession(effectiveThread.id);
+                else if (event.type === "turn.completed") {
+                    if (autoFinishAfterFirstTurn) {
+                        void provider.stopSession(session.id).catch(() => {
+                            // Best effort: one-shot threads should not linger if the provider
+                            // leaves the session open after answering the first task.
+                        });
+                        deps.threadService.markCompletedAndClearSession(effectiveThread.id);
+                        cleanup();
+                    }
+                    else {
+                        deps.threadService.markCompleted(effectiveThread.id);
+                    }
                     broadcastThreadEvent(effectiveThread.id, "status", { status: "completed" });
-                    unsubscribe();
                 }
             });
+            if (timeoutMs) {
+                timeout = setTimeout(() => {
+                    void provider.stopSession(session.id).catch(() => { });
+                    const activity = deps.threadService.addActivity(effectiveThread.id, "session", `Thread stopped after ${Math.round(timeoutMs / 60_000)} minute timeout`, { timeoutMs });
+                    broadcastThreadEvent(effectiveThread.id, "activity", { activity });
+                    deps.threadService.markInterrupted(effectiveThread.id);
+                    broadcastThreadEvent(effectiveThread.id, "status", { status: "interrupted" });
+                    cleanup();
+                }, timeoutMs);
+                if (typeof timeout === "object" && "unref" in timeout && typeof timeout.unref === "function") {
+                    timeout.unref();
+                }
+            }
             deps.threadService.markRunning(effectiveThread.id, session.id);
             broadcastThreadEvent(effectiveThread.id, "status", { status: "running" });
             const historyReplayPrompt = buildThreadHistoryReplayPrompt(deps.threadService, effectiveThread.id);
-            if (message) {
-                const userActivity = deps.threadService.addActivity(effectiveThread.id, "message", message.slice(0, 500), { role: "user" });
-                broadcastThreadEvent(effectiveThread.id, "activity", { activity: userActivity });
-                // Run thread router for the first turn
-                let turnMessage = message;
-                if (historyReplayPrompt) {
-                    turnMessage = `${historyReplayPrompt}\n\n${turnMessage}`;
+            const userActivity = deps.threadService.addActivity(effectiveThread.id, "message", message.slice(0, 500), { role: "user" });
+            broadcastThreadEvent(effectiveThread.id, "activity", { activity: userActivity });
+            // Run thread router for the first turn
+            let turnMessage = message;
+            if (historyReplayPrompt) {
+                turnMessage = `${historyReplayPrompt}\n\n${turnMessage}`;
+            }
+            if (deps.skillRegistry) {
+                const availableSkills = deps.skillRegistry.listEnabled();
+                const routingPlan = routeThread({
+                    message,
+                    availableSkills,
+                    pinnedSkillIds: effectiveThread.skillIds ? (typeof effectiveThread.skillIds === "string" ? JSON.parse(effectiveThread.skillIds) : effectiveThread.skillIds) : null,
+                    kind: effectiveThread.kind,
+                });
+                deps.threadService.update(effectiveThread.id, { routingPlan });
+                broadcastThreadEvent(effectiveThread.id, "updated", { thread: deps.threadService.getById(effectiveThread.id) });
+                turnMessage = `${formatRoutingPlanForPrompt(routingPlan, message.length)}\n\n${message}`;
+            }
+            const sendTurn = async () => {
+                try {
+                    await provider.sendTurn(session.id, turnMessage, options.attachments);
                 }
-                if (deps.skillRegistry) {
-                    const availableSkills = deps.skillRegistry.listEnabled();
-                    const routingPlan = routeThread({
-                        message,
-                        availableSkills,
-                        pinnedSkillIds: effectiveThread.skillIds ? (typeof effectiveThread.skillIds === "string" ? JSON.parse(effectiveThread.skillIds) : effectiveThread.skillIds) : null,
-                        kind: effectiveThread.kind,
-                    });
-                    deps.threadService.update(effectiveThread.id, { routingPlan });
-                    broadcastThreadEvent(effectiveThread.id, "updated", { thread: deps.threadService.getById(effectiveThread.id) });
-                    turnMessage = `${formatRoutingPlanForPrompt(routingPlan, message.length)}\n\n${message}`;
+                catch (err) {
+                    const errorMessage = err instanceof Error ? err.message : String(err);
+                    deps.threadService.markError(effectiveThread.id, errorMessage);
+                    broadcastThreadEvent(effectiveThread.id, "status", { status: "error", error: errorMessage });
+                    cleanup();
+                    if (!detach)
+                        throw err;
                 }
-                await provider.sendTurn(session.id, turnMessage, attachments);
+            };
+            if (detach) {
+                void sendTurn();
+            }
+            else {
+                await sendTurn();
             }
             const updated = deps.threadService.getById(effectiveThread.id) ?? effectiveThread;
-            return { ok: true, message: "Thread started", thread: updated };
+            return { ok: true, message: detach ? "Thread started in background" : "Thread started", thread: updated };
         }
         catch (err) {
             const errorMessage = err instanceof Error ? err.message : String(err);
@@ -212,7 +313,10 @@ export function createThreadControlTool(deps) {
     return {
         name: ToolName.ThreadControl,
         description: "Control agent threads end-to-end: create/list/update/delete threads, run them in parallel, " +
-            "send turns, stop/interrupt, and create pull requests with direct links.",
+            "send turns, stop/interrupt, and create pull requests with direct links. " +
+            "Threads have two kinds: delivery threads are user-owned work items that can be completed, resumed, reviewed, and used to create PRs; " +
+            "delegation threads are helper/sub-agent tasks that auto-finish after one turn and cannot create PRs. " +
+            "Creating or starting a thread requires a non-empty prompt. Scheduled jobs should create delivery threads with detach=true so the scheduler returns after dispatching the turn.",
         tier: "standard",
         category: "agent",
         source: "builtin",
@@ -243,16 +347,39 @@ export function createThreadControlTool(deps) {
                 title: { type: "string", description: "Thread title (create/update)." },
                 model: { type: "string", description: "Optional provider model." },
                 runtimeMode: { type: "string", enum: ["full-access", "supervised"], description: "Execution mode for thread runs." },
-                kind: { type: "string", enum: ["delivery", "delegation"], description: "Thread kind. Delegation threads are helper workers and do not create PRs." },
+                kind: {
+                    type: "string",
+                    enum: ["delivery", "delegation"],
+                    description: "Thread kind. Use delivery for user-owned work that can be reviewed, resumed, merged, or turned into a PR. " +
+                        "Use delegation for helper/sub-agent work; delegation threads auto-finish after one turn and cannot create PRs.",
+                },
                 workingDirectory: { type: "string", description: "Working directory for the thread." },
                 branch: { type: "string", description: "Git branch metadata for the thread." },
-                message: { type: "string", description: "Initial or follow-up user message for start/send." },
+                prompt: {
+                    type: "string",
+                    description: "Required prompt for create/start/send. Prefer this over `message`; `message` is kept as a backward-compatible alias.",
+                },
+                message: { type: "string", description: "Backward-compatible alias for `prompt`." },
                 attachments: {
                     type: "array",
                     description: "Optional attachments for provider sendTurn.",
                     items: { type: "string" },
                 },
-                start: { type: "boolean", description: "For create/create_many: auto-start thread(s) after creation." },
+                start: { type: "boolean", description: "For create/create_many: auto-start thread(s) after creation. Requires `prompt`." },
+                detach: {
+                    type: "boolean",
+                    description: "Return after dispatching the first turn instead of waiting for provider.sendTurn. " +
+                        "Use true for scheduled/cron-created delivery threads so the job creates a normal user-visible thread without blocking the scheduler. Scheduler-triggered starts detach automatically.",
+                },
+                autoStopAfterTurn: {
+                    type: "boolean",
+                    description: "Stop the provider session and clear resumability after the first turn completes. " +
+                        "Delegation threads always do this. Leave false for normal delivery threads that the user may review, resume, merge, or delete later.",
+                },
+                timeoutMinutes: {
+                    type: "number",
+                    description: "Maximum runtime before stopping the provider session. Scheduler-triggered starts default to 240 minutes.",
+                },
                 threads: {
                     type: "array",
                     description: "For create_many: array of thread specs to create in one call.",
@@ -267,8 +394,12 @@ export function createThreadControlTool(deps) {
                             branch: { type: "string" },
                             sessionId: { type: "string" },
                             start: { type: "boolean" },
+                            prompt: { type: "string" },
                             message: { type: "string" },
                             attachments: { type: "array", items: { type: "string" } },
+                            detach: { type: "boolean" },
+                            autoStopAfterTurn: { type: "boolean" },
+                            timeoutMinutes: { type: "number" },
                         },
                         required: ["title"],
                     },
@@ -313,13 +444,17 @@ export function createThreadControlTool(deps) {
                         return { ok: true, message: "Thread loaded", data: { thread } };
                     }
                     case "create": {
+                        const prompt = normalizePrompt(input.message, input.prompt);
+                        if (!prompt) {
+                            return { ok: false, message: "create requires non-empty `prompt`." };
+                        }
                         const resolvedProvider = resolveProviderId(context);
                         if (!resolvedProvider.providerId) {
                             return { ok: false, message: resolvedProvider.error ?? "Unable to resolve a provider for this thread." };
                         }
                         const selectedProviderId = resolvedProvider.providerId;
                         const selectedDefaults = resolveSelectedThreadDefaults(context);
-                        const thread = deps.threadService.create({
+                        let thread = deps.threadService.create({
                             userId,
                             sessionId: input.sessionId,
                             title: input.title?.trim() || "New Thread",
@@ -331,10 +466,35 @@ export function createThreadControlTool(deps) {
                             branch: input.branch,
                         });
                         broadcastThreadEvent(thread.id, "created", { thread });
+                        try {
+                            const isolatedThread = await createManagedDeliveryWorktree(thread);
+                            if (isolatedThread.id === thread.id && isolatedThread.workingDirectory !== thread.workingDirectory) {
+                                thread = isolatedThread;
+                                broadcastThreadEvent(thread.id, "updated", { thread });
+                            }
+                        }
+                        catch (err) {
+                            const message = err instanceof Error ? err.message : String(err);
+                            deps.threadService.markError(thread.id, message);
+                            broadcastThreadEvent(thread.id, "status", { status: "error", error: message });
+                            return {
+                                ok: false,
+                                message: `Thread created but failed to create delivery worktree: ${message}`,
+                                data: { thread: deps.threadService.getById(thread.id) ?? thread },
+                            };
+                        }
                         if (!input.start) {
+                            const activity = deps.threadService.addActivity(thread.id, "message", prompt.slice(0, 500), { role: "user" });
+                            broadcastThreadEvent(thread.id, "activity", { activity });
                             return { ok: true, message: "Thread created", data: { thread } };
                         }
-                        const started = await startThread(context, thread, input.message, input.attachments);
+                        const started = await startThread(context, thread, {
+                            message: prompt,
+                            attachments: input.attachments,
+                            detach: input.detach,
+                            autoStopAfterTurn: input.autoStopAfterTurn,
+                            timeoutMinutes: input.timeoutMinutes,
+                        });
                         if (!started.ok) {
                             return {
                                 ok: false,
@@ -352,6 +512,13 @@ export function createThreadControlTool(deps) {
                         if (!input.threads || input.threads.length === 0) {
                             return { ok: false, message: "create_many requires non-empty `threads`." };
                         }
+                        const missingPrompt = input.threads.find((spec) => {
+                            const prompt = normalizePrompt(spec.message, spec.prompt) ?? normalizePrompt(input.message, input.prompt);
+                            return !prompt;
+                        });
+                        if (missingPrompt) {
+                            return { ok: false, message: `create_many requires non-empty prompt for thread '${missingPrompt.title}'.` };
+                        }
                         const validatedSpecs = input.threads.map((spec) => ({
                             spec,
                             resolvedProvider: resolveProviderId(context),
@@ -363,10 +530,11 @@ export function createThreadControlTool(deps) {
                                 message: firstResolutionError.resolvedProvider.error ?? `Unable to resolve a provider for thread '${firstResolutionError.spec.title}'.`,
                             };
                         }
-                        const created = validatedSpecs.map(({ spec, resolvedProvider }) => {
+                        const created = await Promise.all(validatedSpecs.map(async ({ spec, resolvedProvider }) => {
                             const selectedProviderId = resolvedProvider.providerId;
                             const selectedDefaults = resolveSelectedThreadDefaults(context);
-                            const thread = deps.threadService.create({
+                            const prompt = (normalizePrompt(spec.message, spec.prompt) ?? normalizePrompt(input.message, input.prompt));
+                            let thread = deps.threadService.create({
                                 userId,
                                 sessionId: spec.sessionId ?? input.sessionId,
                                 title: spec.title?.trim() || "New Thread",
@@ -378,11 +546,44 @@ export function createThreadControlTool(deps) {
                                 branch: spec.branch ?? input.branch,
                             });
                             broadcastThreadEvent(thread.id, "created", { thread });
-                            return { thread, spec };
-                        });
+                            try {
+                                const isolatedThread = await createManagedDeliveryWorktree(thread);
+                                if (isolatedThread.id === thread.id && isolatedThread.workingDirectory !== thread.workingDirectory) {
+                                    thread = isolatedThread;
+                                    broadcastThreadEvent(thread.id, "updated", { thread });
+                                }
+                            }
+                            catch (err) {
+                                const message = err instanceof Error ? err.message : String(err);
+                                deps.threadService.markError(thread.id, message);
+                                broadcastThreadEvent(thread.id, "status", { status: "error", error: message });
+                                return { thread: deps.threadService.getById(thread.id) ?? thread, spec, prompt, worktreeError: message };
+                            }
+                            return { thread, spec, prompt };
+                        }));
+                        const worktreeFailures = created.filter((entry) => entry.worktreeError);
+                        if (worktreeFailures.length > 0) {
+                            return {
+                                ok: false,
+                                message: `Created ${created.length} thread(s), ${worktreeFailures.length} failed to create delivery worktrees.`,
+                                data: {
+                                    threads: created.map((entry) => entry.thread),
+                                    failedWorktrees: worktreeFailures.map((entry) => ({
+                                        threadId: entry.thread.id,
+                                        message: entry.worktreeError,
+                                    })),
+                                },
+                            };
+                        }
                         const startTargets = created.filter(({ spec }) => spec.start === true || input.start === true);
-                        const startResults = await Promise.all(startTargets.map(async ({ thread, spec }) => {
-                            const started = await startThread(context, thread, spec.message ?? input.message, spec.attachments ?? input.attachments);
+                        const startResults = await Promise.all(startTargets.map(async ({ thread, spec, prompt }) => {
+                            const started = await startThread(context, thread, {
+                                message: prompt,
+                                attachments: spec.attachments ?? input.attachments,
+                                detach: spec.detach ?? input.detach,
+                                autoStopAfterTurn: spec.autoStopAfterTurn ?? input.autoStopAfterTurn,
+                                timeoutMinutes: spec.timeoutMinutes ?? input.timeoutMinutes,
+                            });
                             return {
                                 threadId: thread.id,
                                 ok: started.ok,
@@ -395,6 +596,12 @@ export function createThreadControlTool(deps) {
                         for (const started of startResults) {
                             threadById.set(started.threadId, started.thread);
                         }
+                        for (const { thread, prompt, spec } of created) {
+                            if (spec.start === true || input.start === true)
+                                continue;
+                            const activity = deps.threadService.addActivity(thread.id, "message", prompt.slice(0, 500), { role: "user" });
+                            broadcastThreadEvent(thread.id, "activity", { activity });
+                        }
                         const threads = [...threadById.values()];
                         return {
                             ok: failedStarts.length === 0,
@@ -464,10 +671,19 @@ export function createThreadControlTool(deps) {
                     case "start": {
                         if (!input.threadId)
                             return { ok: false, message: "start requires `threadId`." };
+                        const prompt = normalizePrompt(input.message, input.prompt);
+                        if (!prompt)
+                            return { ok: false, message: "start requires non-empty `prompt`." };
                         const thread = getAccessibleThread(input.threadId, userId);
                         if (!thread)
                             return { ok: false, message: "Thread not found." };
-                        const started = await startThread(context, thread, input.message, input.attachments);
+                        const started = await startThread(context, thread, {
+                            message: prompt,
+                            attachments: input.attachments,
+                            detach: input.detach,
+                            autoStopAfterTurn: input.autoStopAfterTurn,
+                            timeoutMinutes: input.timeoutMinutes,
+                        });
                         return {
                             ok: started.ok,
                             message: started.message,
@@ -477,8 +693,9 @@ export function createThreadControlTool(deps) {
                     case "send": {
                         if (!input.threadId)
                             return { ok: false, message: "send requires `threadId`." };
-                        if (!input.message?.trim())
-                            return { ok: false, message: "send requires non-empty `message`." };
+                        const prompt = normalizePrompt(input.message, input.prompt);
+                        if (!prompt)
+                            return { ok: false, message: "send requires non-empty `prompt`." };
                         const thread = getAccessibleThread(input.threadId, userId);
                         if (!thread)
                             return { ok: false, message: "Thread not found." };
@@ -490,8 +707,8 @@ export function createThreadControlTool(deps) {
                             return { ok: false, message: `Provider '${thread.providerId}' not found` };
                         deps.threadService.update(thread.id, { status: "running", error: null, completedAt: null });
                         broadcastThreadEvent(thread.id, "status", { status: "running" });
-                        await provider.sendTurn(thread.providerSessionId, input.message, input.attachments);
-                        const activity = deps.threadService.addActivity(thread.id, "message", input.message.slice(0, 500), { role: "user" });
+                        await provider.sendTurn(thread.providerSessionId, prompt, input.attachments);
+                        const activity = deps.threadService.addActivity(thread.id, "message", prompt.slice(0, 500), { role: "user" });
                         broadcastThreadEvent(thread.id, "activity", { activity });
                         return { ok: true, message: "Turn sent", data: { threadId: thread.id } };
                     }