opencandle 0.11.1 → 0.12.0

package/dist/gui/server/server.js

@@ -0,0 +1,259 @@
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { createServer } from "node:http";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AuthStorage, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, ModelRegistry, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { createOpenCandleSession } from "../../index.js";
+import { assertSupportedNodeVersion } from "../../infra/node-version.js";
+import { createAskUserBridge } from "./ask-user-bridge.js";
+import { createLocalAutomationHeartbeat, normalizeAutomationHeartbeatMs, } from "./automation-heartbeat.js";
+import { BackgroundQuoteRefreshes, createBackgroundQuotePoller, } from "./background-quotes.js";
+import { createInitialGuiSessionManager } from "./gui-session-manager.js";
+import { createHttpRequestHandler, resolveSessionManagerById } from "./http-routes.js";
+import { createToolInvokeController } from "./invoke-tool.js";
+import { createLocalSessionCoordinator } from "./local-session-coordinator.js";
+import { buildMarketStateQuoteSnapshot } from "./market-state-api.js";
+import { createModelSetupController } from "./model-setup.js";
+import { isTrustedPrivateApiRequest } from "./private-api-access.js";
+import { QuoteSnapshotStore } from "./quote-snapshot-store.js";
+import { createSessionActionsController } from "./session-actions.js";
+import { createGracefulShutdown } from "./shutdown.js";
+import { acquireWriterLock, migrateWriterLockScope, refreshWriterLock, releaseWriterLock, writerLockScopeForSession, } from "./writer-lock.js";
+import { createWsHub } from "./ws-hub.js";
+assertSupportedNodeVersion();
+const cwd = process.cwd();
+const host = process.env.OPENCANDLE_GUI_HOST ?? "127.0.0.1";
+const port = Number(process.env.OPENCANDLE_GUI_PORT ?? 14567);
+const automationHeartbeatMs = normalizeAutomationHeartbeatMs(process.env.OPENCANDLE_AUTOMATION_HEARTBEAT_MS);
+const allowRemotePrivateApi = process.env.OPENCANDLE_GUI_ALLOW_REMOTE_PRIVATE_API === "1";
+const privateApiSessionToken = randomBytes(32).toString("base64url");
+const localCoordinatorSecret = randomBytes(32).toString("base64url");
+const localCoordinatorEndpoint = `http://${coordinatorEndpointHost(host)}:${port}`;
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const webDist = resolveGuiWebDist(__dirname);
+const agentDir = getAgentDir();
+const authStorage = AuthStorage.create();
+const modelRegistry = ModelRegistry.create(authStorage);
+const settingsManager = SettingsManager.create(cwd, agentDir);
+const initialSessionManager = createInitialGuiSessionManager(cwd);
+let sessionManager = initialSessionManager;
+const sessionDir = sessionManager.getSessionDir();
+const initialWriterLockScope = writerLockScopeForSession(sessionManager);
+const lockResult = await acquireWriterLock(initialWriterLockScope, "gui", {
+    coordinatorEndpoint: localCoordinatorEndpoint,
+    coordinatorSecret: localCoordinatorSecret,
+});
+let activeWriterLockScope = initialWriterLockScope;
+let currentWriterLockLost = false;
+let wsHub;
+let quotePoller;
+const askUserBridge = createAskUserBridge({
+    broadcast: (message) => wsHub.broadcast(message),
+    getSessionId: () => sessionManager.getSessionId(),
+});
+const runtime = await createAgentSessionRuntime(async (opts) => {
+    const services = await createAgentSessionServices({
+        cwd: opts.cwd,
+        agentDir: opts.agentDir,
+        authStorage,
+        settingsManager,
+        modelRegistry,
+    });
+    const result = await createOpenCandleSession({
+        cwd: opts.cwd,
+        agentDir: opts.agentDir,
+        authStorage,
+        modelRegistry,
+        settingsManager,
+        sessionManager: opts.sessionManager,
+        askUserHandler: askUserBridge.ask,
+    });
+    return { ...result, services, diagnostics: services.diagnostics };
+}, { cwd, agentDir, sessionManager });
+let session = runtime.session;
+function syncCurrentWriterLockScope() {
+    if (currentWriterLockLost)
+        throw new Error("OpenCandle is reconnecting to this session.");
+    if (lockResult.role !== "writer")
+        return;
+    const nextScope = writerLockScopeForSession(sessionManager);
+    if (nextScope === activeWriterLockScope)
+        return;
+    if (migrateWriterLockScope(activeWriterLockScope, nextScope)) {
+        activeWriterLockScope = nextScope;
+    }
+    else {
+        currentWriterLockLost = true;
+        throw new Error("OpenCandle is reconnecting to this session.");
+    }
+}
+const heartbeat = setInterval(() => {
+    try {
+        syncCurrentWriterLockScope();
+        refreshWriterLock(activeWriterLockScope);
+    }
+    catch {
+        clearInterval(heartbeat);
+    }
+}, 5000);
+const backgroundQuoteRefreshes = new BackgroundQuoteRefreshes();
+const localSessionCoordinator = createLocalSessionCoordinator();
+const quoteSnapshotStore = new QuoteSnapshotStore(() => buildMarketStateQuoteSnapshot());
+quotePoller = createBackgroundQuotePoller({
+    getClientCount: () => wsHub.getClientCount(),
+    getSessionManager: () => sessionManager,
+    refreshes: backgroundQuoteRefreshes,
+    broadcastState: () => wsHub.broadcastState(),
+});
+const localAutomationHeartbeat = createLocalAutomationHeartbeat({
+    role: lockResult.role,
+    getSessionId: () => sessionManager.getSessionId(),
+    intervalMs: automationHeartbeatMs,
+});
+const modelSetupController = createModelSetupController({
+    role: lockResult.role,
+    getSession: () => session,
+    getSessionManager: () => sessionManager,
+    broadcastState: () => wsHub.broadcastState(),
+});
+const toolInvokeController = createToolInvokeController({
+    role: lockResult.role,
+    getSessionManager: () => sessionManager,
+    broadcastState: () => wsHub.broadcastState(),
+    broadcastSessionSnapshot: (targetSessionManager) => wsHub.broadcastSessionSnapshot(targetSessionManager),
+    broadcastSessions: () => wsHub.broadcastSessions(),
+    onMarketStateChanged: () => quoteSnapshotStore.invalidate(),
+    askUserHandler: askUserBridge.ask,
+    askUserHandlerForSessionId: (sessionId) => askUserBridge.askForSession(sessionId),
+    localCoordinatorEndpoint,
+    localCoordinatorSecret,
+    localSessionCoordinator,
+    syncWriterLockScope: syncCurrentWriterLockScope,
+    resolveSessionManager: (sessionId) => resolveSessionManagerById({ cwd, sessionDir, getSessionManager: () => sessionManager }, sessionId),
+});
+const sessionActionsController = createSessionActionsController({
+    role: lockResult.role,
+    cwd,
+    sessionDir,
+    getSession: () => session,
+    getSessionManager: () => sessionManager,
+    getModelSetupState: () => modelSetupController.buildCurrentModelSetupState(),
+    askUserBridge,
+    runtime,
+    sendBoot: (client) => wsHub.sendBoot(client),
+    broadcastState: () => wsHub.broadcastState(),
+    broadcastSessions: () => wsHub.broadcastSessions(),
+    localSessionCoordinator,
+});
+wsHub = createWsHub({
+    role: lockResult.role,
+    lock: lockResult.lock,
+    cwd,
+    sessionDir,
+    getSession: () => session,
+    getSessionManager: () => sessionManager,
+    backgroundQuoteRefreshes,
+    askUserBridge,
+    modelSetupController,
+    toolInvokeController,
+    sessionActionsController,
+    onClientCountChanged: () => quotePoller.updatePoller(),
+    isTrustedRequest: (req) => isTrustedPrivateApiRequest(req.headers, privateApiSessionToken, req.socket.remoteAddress, {
+        allowRemote: allowRemotePrivateApi,
+    }),
+});
+let unsubscribeSession = wsHub.subscribeToSessionEvents();
+runtime.setRebindSession(async (nextSession) => {
+    const nextWriterLockScope = writerLockScopeForSession(nextSession.sessionManager);
+    if (lockResult.role === "writer" && nextWriterLockScope !== activeWriterLockScope) {
+        const nextLockResult = await acquireWriterLock(nextWriterLockScope, "gui", {
+            coordinatorEndpoint: localCoordinatorEndpoint,
+            coordinatorSecret: localCoordinatorSecret,
+        });
+        if (nextLockResult.role !== "writer") {
+            throw new Error("OpenCandle is reconnecting to this session.");
+        }
+        releaseWriterLock(activeWriterLockScope);
+        activeWriterLockScope = nextWriterLockScope;
+    }
+    unsubscribeSession();
+    session = nextSession;
+    sessionManager = nextSession.sessionManager;
+    unsubscribeSession = wsHub.subscribeToSessionEvents();
+});
+const httpRequestHandler = createHttpRequestHandler({
+    host,
+    port,
+    webDist,
+    role: lockResult.role,
+    cwd,
+    agentDir,
+    sessionDir,
+    privateApiSessionToken,
+    localCoordinatorEndpoint,
+    localCoordinatorSecret,
+    allowRemotePrivateApi,
+    syncCurrentWriterLockScope,
+    getSession: () => session,
+    getSessionManager: () => sessionManager,
+    createSessionForManager: async (targetSessionManager) => createOpenCandleSession({
+        cwd,
+        agentDir,
+        authStorage,
+        modelRegistry,
+        settingsManager,
+        sessionManager: targetSessionManager,
+        askUserHandler: askUserBridge.askForSession(targetSessionManager.getSessionId()),
+    }),
+    wsHub,
+    modelSetupController,
+    sessionActionsController,
+    toolInvokeController,
+    quoteSnapshotStore,
+    localSessionCoordinator,
+});
+const server = createServer((req, res) => {
+    void httpRequestHandler(req, res);
+});
+server.on("upgrade", (req, socket) => wsHub.handleUpgrade(req, socket));
+server.listen(port, host, () => {
+    console.log(`OpenCandle GUI listening on http://${host}:${port}`);
+    if (host === "0.0.0.0") {
+        console.log(`OpenCandle GUI is accepting LAN/Tailscale connections on port ${port}`);
+    }
+    if (allowRemotePrivateApi) {
+        console.log("OpenCandle GUI private market-state API accepts cookie-authenticated remote requests.");
+    }
+    console.log(`Writer role: ${lockResult.role}`);
+    localAutomationHeartbeat.start();
+});
+const shutdown = createGracefulShutdown({
+    server,
+    cleanup: async () => {
+        clearInterval(heartbeat);
+        quotePoller.stop();
+        localAutomationHeartbeat.stop();
+        wsHub.closeClients();
+        unsubscribeSession();
+        releaseWriterLock(activeWriterLockScope);
+        await runtime.dispose();
+    },
+    exit: (code) => process.exit(code),
+});
+function coordinatorEndpointHost(bindHost) {
+    if (bindHost === "0.0.0.0")
+        return "127.0.0.1";
+    if (bindHost === "::")
+        return "[::1]";
+    return bindHost.includes(":") && !bindHost.startsWith("[") ? `[${bindHost}]` : bindHost;
+}
+function resolveGuiWebDist(serverDir) {
+    const candidates = [
+        resolve(serverDir, "../web/dist"),
+        resolve(serverDir, "../../../gui/web/dist"),
+    ];
+    return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
+}
+process.once("SIGINT", shutdown);
+process.once("SIGTERM", shutdown);

package/dist/gui/server/session-actions.d.ts

@@ -0,0 +1,60 @@
+import { type AgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import type { LocalSessionCoordinator, SessionActionSource } from "./local-session-coordinator.js";
+import type { ModelSetupState } from "./model-setup.js";
+import { type PromptObservation } from "./prompt-observation.js";
+interface AskUserBridge {
+    answer(id: string, answer: string): boolean;
+    cancel(id: string): boolean;
+}
+interface SessionActionsRuntime {
+    newSession(): Promise<{
+        cancelled: boolean;
+    }>;
+    switchSession(path: string): Promise<{
+        cancelled: boolean;
+    }>;
+}
+interface SessionActionClient {
+    send(message: unknown): void;
+}
+export interface SessionActionsController {
+    handleAskUserAnswer(id: string, value: unknown, action?: SessionActionMeta): Promise<void>;
+    handleAskUserCancel(id: string, action?: SessionActionMeta): Promise<void>;
+    handleNewSession(): Promise<void>;
+    handleOpenSession(path: string): Promise<void>;
+    handleRenameSession(path: string, name: string): Promise<void>;
+    handleDeleteSession(client: SessionActionClient, path: string): Promise<void>;
+}
+export interface SessionActionsControllerOptions {
+    role: string;
+    cwd: string;
+    sessionDir: string;
+    getSession: () => AgentSession;
+    getSessionManager: () => SessionManager;
+    getModelSetupState: () => ModelSetupState;
+    askUserBridge: AskUserBridge;
+    runtime: SessionActionsRuntime;
+    sendBoot: (client: SessionActionClient) => void;
+    broadcastState: () => void;
+    broadcastSessions: () => void;
+    localSessionCoordinator?: LocalSessionCoordinator;
+    now?: () => number;
+}
+export interface SessionActionMeta {
+    sessionId?: string;
+    actionId?: string;
+    source?: SessionActionSource;
+    allowProxy?: boolean;
+}
+export declare function createSessionActionsController({ role, cwd, sessionDir, getSessionManager, askUserBridge, runtime, sendBoot, broadcastState, broadcastSessions, localSessionCoordinator, }: SessionActionsControllerOptions): SessionActionsController;
+export declare function promptAndSettle(runSession: AgentSession, prompt: string, beforeIds: Set<string>, observation?: PromptObservation, options?: {
+    images?: Array<{
+        type: "image";
+        data: string;
+        mimeType: string;
+    }>;
+}): Promise<void>;
+export declare function replayObservedWorkflowPromptIfNeeded(runSession: AgentSession, originalPrompt: string, observation?: PromptObservation): Promise<void>;
+export declare function renameSessionFile(cwd: string, sessionDir: string, sessionPath: string, nextName: string): Promise<void>;
+export declare function deleteSessionFile(cwd: string, sessionDir: string, sessionPath: string): Promise<void>;
+export {};

package/dist/gui/server/session-actions.js

@@ -0,0 +1,218 @@
+import { unlink } from "node:fs/promises";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { selectReplayPrompt } from "./prompt-observation.js";
+import { waitForNewEntryId, waitForResolvedToolCalls, waitForSessionTurnSettlement, } from "./session-entry-wait.js";
+import { readWriterLock, writerLockScopeForSession } from "./writer-lock.js";
+export function createSessionActionsController({ role, cwd, sessionDir, getSessionManager, askUserBridge, runtime, sendBoot, broadcastState, broadcastSessions, localSessionCoordinator, }) {
+    function ensureWriter() {
+        if (role !== "writer")
+            throw new Error("Read-only follower mode");
+    }
+    async function handleAskUserAnswer(id, value, action) {
+        const answer = String(value ?? "").trim();
+        if (!answer)
+            throw new Error("Answer cannot be empty");
+        if (shouldProxyAskUserAction(action)) {
+            if (await proxyAskUserAction("ask_user.answer", { id, answer }, action))
+                return;
+            throw new Error("OpenCandle is reconnecting to this session.");
+        }
+        await runCoordinatedSessionAction("ask_user.answer", { id, answer }, action, async () => {
+            if (!askUserBridge.answer(id, answer))
+                throw new Error("Unknown or resolved question");
+        });
+    }
+    async function handleAskUserCancel(id, action) {
+        if (shouldProxyAskUserAction(action)) {
+            if (await proxyAskUserAction("ask_user.cancel", { id }, action))
+                return;
+            throw new Error("OpenCandle is reconnecting to this session.");
+        }
+        await runCoordinatedSessionAction("ask_user.cancel", { id }, action, async () => {
+            if (!askUserBridge.cancel(id))
+                throw new Error("Unknown or resolved question");
+        });
+    }
+    async function handleNewSession() {
+        ensureWriter();
+        const result = await runtime.newSession();
+        if (result.cancelled)
+            throw new Error("Session switch cancelled");
+    }
+    async function handleOpenSession(path) {
+        ensureWriter();
+        const sessions = await SessionManager.list(cwd, sessionDir);
+        const match = sessions.find((candidate) => candidate.path === path);
+        if (!match)
+            throw new Error("Unknown saved session");
+        const result = await runtime.switchSession(match.path);
+        if (result.cancelled)
+            throw new Error("Session switch cancelled");
+    }
+    async function handleRenameSession(path, name) {
+        ensureWriter();
+        const nextName = name.trim();
+        if (!nextName)
+            throw new Error("Session name cannot be empty");
+        const sessionManager = getSessionManager();
+        if (sessionManager.getSessionFile() === path) {
+            sessionManager.appendSessionInfo(nextName);
+            return;
+        }
+        await renameSessionFile(cwd, sessionDir, path, nextName);
+    }
+    async function handleDeleteSession(client, path) {
+        ensureWriter();
+        const deletingCurrent = getSessionManager().getSessionFile() === path;
+        await deleteSessionFile(cwd, sessionDir, path);
+        if (deletingCurrent) {
+            await handleNewSession();
+            sendBoot(client);
+            broadcastState();
+        }
+        broadcastSessions();
+    }
+    return {
+        handleAskUserAnswer,
+        handleAskUserCancel,
+        handleNewSession,
+        handleOpenSession,
+        handleRenameSession,
+        handleDeleteSession,
+    };
+    async function runCoordinatedSessionAction(actionType, payload, action, handler) {
+        if (!localSessionCoordinator || !action?.actionId) {
+            await handler();
+            return;
+        }
+        const sessionId = action.sessionId?.trim();
+        if (!sessionId)
+            throw new Error("sessionId is required");
+        const result = await localSessionCoordinator.runSessionAction({
+            sessionId,
+            actionId: action.actionId,
+            actionType,
+            payload,
+            source: action.source ?? "gui",
+        }, async () => {
+            await handler();
+            return { accepted: true };
+        });
+        if (!result.ok)
+            throw new Error(result.message);
+    }
+    async function proxyAskUserAction(actionType, payload, action) {
+        if (action?.allowProxy === false)
+            return false;
+        const sessionManager = await resolveActionSessionManager(action);
+        const lock = readWriterLock(writerLockScopeForSession(sessionManager));
+        if (!lock?.coordinatorEndpoint || !lock.coordinatorSecret || lock.pid === process.pid) {
+            return false;
+        }
+        if (lock.processKind === "tui")
+            return false;
+        const endpoint = new URL("/api/local-coordinator/ask-user", lock.coordinatorEndpoint);
+        let response;
+        try {
+            response = await fetch(endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-opencandle-coordinator-secret": lock.coordinatorSecret,
+                },
+                body: JSON.stringify({
+                    sessionId: action?.sessionId,
+                    actionId: action?.actionId || "",
+                    actionType,
+                    payload,
+                }),
+            });
+        }
+        catch {
+            return false;
+        }
+        if (response.ok)
+            return true;
+        const body = (await response.json().catch(() => ({})));
+        throw new Error(body.error || "OpenCandle is reconnecting to this session.");
+    }
+    function shouldProxyAskUserAction(action) {
+        if (role !== "writer")
+            return true;
+        const targetSessionId = action?.sessionId?.trim();
+        return Boolean(targetSessionId && targetSessionId !== getSessionManager().getSessionId());
+    }
+    async function resolveActionSessionManager(action) {
+        const current = getSessionManager();
+        const targetSessionId = action?.sessionId?.trim();
+        if (!targetSessionId || targetSessionId === current.getSessionId())
+            return current;
+        const sessions = await SessionManager.list(cwd, sessionDir);
+        const match = sessions.find((candidate) => candidate.id === targetSessionId);
+        if (!match)
+            throw new Error("Unknown saved session");
+        return SessionManager.open(match.path, sessionDir, cwd);
+    }
+}
+export async function promptAndSettle(runSession, prompt, beforeIds, observation, options) {
+    await runSession.prompt(prompt, options);
+    await settleWithEventProgress(runSession);
+    await waitForNewEntryId(() => runSession.sessionManager.getEntries().map((entry) => entry.id), beforeIds);
+    await waitForResolvedToolCalls(() => runSession.sessionManager.getEntries());
+    await replayObservedWorkflowPromptIfNeeded(runSession, prompt, observation);
+}
+/**
+ * Settle wait fed by a session-event counter: a single long model generation
+ * keeps isStreaming/pendingMessageCount frozen for its whole duration, and
+ * without an activity signal the stall detector killed healthy long turns.
+ */
+async function settleWithEventProgress(runSession) {
+    let progressToken = 0;
+    const unsubscribe = runSession.subscribe(() => {
+        progressToken += 1;
+    });
+    try {
+        await waitForSessionTurnSettlement(() => ({
+            isStreaming: runSession.isStreaming,
+            pendingMessageCount: runSession.pendingMessageCount,
+            progressToken,
+        }));
+    }
+    finally {
+        unsubscribe();
+    }
+}
+export async function replayObservedWorkflowPromptIfNeeded(runSession, originalPrompt, observation) {
+    if (!observation)
+        return;
+    const replayPrompt = selectReplayPrompt(observation, originalPrompt);
+    if (!replayPrompt)
+        return;
+    // V1 attachment replay is text-only: the recorded expanded prompt is
+    // re-sent, but image bytes are not replayed.
+    await runSession.prompt(replayPrompt, {
+        expandPromptTemplates: false,
+        source: "extension",
+    });
+    await settleWithEventProgress(runSession);
+    await waitForResolvedToolCalls(() => runSession.sessionManager.getEntries());
+}
+export async function renameSessionFile(cwd, sessionDir, sessionPath, nextName) {
+    const target = await resolveListedSession(cwd, sessionDir, sessionPath);
+    const name = nextName.trim();
+    if (!name)
+        throw new Error("Session name cannot be empty");
+    const manager = SessionManager.open(target.path);
+    manager.appendSessionInfo(name);
+}
+export async function deleteSessionFile(cwd, sessionDir, sessionPath) {
+    const target = await resolveListedSession(cwd, sessionDir, sessionPath);
+    await unlink(target.path);
+}
+async function resolveListedSession(cwd, sessionDir, sessionPath) {
+    const sessions = await SessionManager.list(cwd, sessionDir);
+    const target = sessions.find((session) => session.path === sessionPath);
+    if (!target)
+        throw new Error("Unknown saved session");
+    return target;
+}

package/dist/gui/server/session-entry-wait.d.ts

@@ -0,0 +1,27 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+export interface WaitForEntryCountOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+}
+export interface WaitForSessionTurnSettlementOptions extends WaitForEntryCountOptions {
+    idleGraceMs?: number;
+}
+export interface SessionRunStatus {
+    isStreaming: boolean;
+    pendingMessageCount: number;
+    /**
+     * Monotonic activity signal (e.g. a session-event counter). A single long
+     * model generation keeps isStreaming/pendingMessageCount frozen for its
+     * whole duration; this token is what distinguishes it from a hung run.
+     */
+    progressToken?: number;
+}
+export interface UnresolvedToolCall {
+    id: string;
+    name: string;
+}
+export declare function waitForEntryCount(getCount: () => number, previousCount: number, options?: WaitForEntryCountOptions): Promise<void>;
+export declare function waitForNewEntryId(getIds: () => string[], previousIds: Set<string>, options?: WaitForEntryCountOptions): Promise<void>;
+export declare function waitForSessionTurnSettlement(getStatus: () => SessionRunStatus, options?: WaitForSessionTurnSettlementOptions): Promise<void>;
+export declare function findUnresolvedToolCalls(entries: SessionEntry[]): UnresolvedToolCall[];
+export declare function waitForResolvedToolCalls(getEntries: () => SessionEntry[], options?: WaitForEntryCountOptions): Promise<void>;