opencandle 0.5.0 → 0.6.0

package/gui/server/session-actions.ts

@@ -1,5 +1,190 @@
 import { unlink } from "node:fs/promises";
-import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import type { ModelSetupState } from "./model-setup.js";
+import { type PromptObservation, selectReplayPrompt } from "./prompt-observation.js";
+import { waitForNewEntryId, waitForSessionTurnSettlement } from "./session-entry-wait.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 {
+  handlePrompt(prompt: string): Promise<void>;
+  handleAskUserAnswer(id: string, value: unknown): Promise<void>;
+  handleAskUserCancel(id: string): 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;
+  now?: () => number;
+}
+
+export function createSessionActionsController({
+  role,
+  cwd,
+  sessionDir,
+  getSession,
+  getSessionManager,
+  getModelSetupState,
+  askUserBridge,
+  runtime,
+  sendBoot,
+  broadcastState,
+  broadcastSessions,
+  now = Date.now,
+}: SessionActionsControllerOptions): SessionActionsController {
+  function ensureWriter(): void {
+    if (role !== "writer") throw new Error("Read-only follower mode");
+  }
+
+  async function handlePrompt(prompt: string): Promise<void> {
+    ensureWriter();
+
+    const modelSetup = getModelSetupState();
+    const sessionManager = getSessionManager();
+    const trimmedPrompt = prompt.trim();
+    if (!trimmedPrompt.startsWith("/") && modelSetup.requirement !== "ready") {
+      sessionManager.appendMessage({ role: "user", content: prompt, timestamp: now() });
+      broadcastState();
+      const message =
+        modelSetup.requirement === "select_model"
+          ? "Choose an available model before chat can run. OpenCandle found configured credentials but no active model."
+          : "Connect an AI model before chat can run. Paste a Google Gemini, OpenAI, or Anthropic API key in the setup panel.";
+      sessionManager.appendCustomMessageEntry("opencandle-model-setup", message, true, {
+        source: "gui",
+        requirement: modelSetup.requirement,
+      });
+      broadcastState();
+      return;
+    }
+
+    const beforeIds = new Set(sessionManager.getEntries().map((entry) => entry.id));
+    await promptAndSettle(getSession(), prompt, beforeIds);
+    broadcastState();
+  }
+
+  async function handleAskUserAnswer(id: string, value: unknown): Promise<void> {
+    ensureWriter();
+    const answer = String(value ?? "").trim();
+    if (!answer) throw new Error("Answer cannot be empty");
+    if (!askUserBridge.answer(id, answer)) throw new Error("Unknown or resolved question");
+  }
+
+  async function handleAskUserCancel(id: string): Promise<void> {
+    ensureWriter();
+    if (!askUserBridge.cancel(id)) throw new Error("Unknown or resolved question");
+  }
+
+  async function handleNewSession(): Promise<void> {
+    ensureWriter();
+    const result = await runtime.newSession();
+    if (result.cancelled) throw new Error("Session switch cancelled");
+  }
+
+  async function handleOpenSession(path: string): Promise<void> {
+    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: string, name: string): Promise<void> {
+    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: SessionActionClient, path: string): Promise<void> {
+    ensureWriter();
+    const deletingCurrent = getSessionManager().getSessionFile() === path;
+    await deleteSessionFile(cwd, sessionDir, path);
+    if (deletingCurrent) {
+      await handleNewSession();
+      sendBoot(client);
+      broadcastState();
+    }
+    broadcastSessions();
+  }
+
+  return {
+    handlePrompt,
+    handleAskUserAnswer,
+    handleAskUserCancel,
+    handleNewSession,
+    handleOpenSession,
+    handleRenameSession,
+    handleDeleteSession,
+  };
+}
+
+export async function promptAndSettle(
+  runSession: AgentSession,
+  prompt: string,
+  beforeIds: Set<string>,
+  observation?: PromptObservation,
+): Promise<void> {
+  await runSession.prompt(prompt);
+  await waitForSessionTurnSettlement(() => ({
+    isStreaming: runSession.isStreaming,
+    pendingMessageCount: runSession.pendingMessageCount,
+  }));
+  await waitForNewEntryId(
+    () => runSession.sessionManager.getEntries().map((entry) => entry.id),
+    beforeIds,
+  );
+  await replayObservedWorkflowPromptIfNeeded(runSession, prompt, observation);
+}
+
+export async function replayObservedWorkflowPromptIfNeeded(
+  runSession: AgentSession,
+  originalPrompt: string,
+  observation?: PromptObservation,
+): Promise<void> {
+  if (!observation) return;
+  const replayPrompt = selectReplayPrompt(observation, originalPrompt);
+  if (!replayPrompt) return;
+
+  await runSession.prompt(replayPrompt, {
+    expandPromptTemplates: false,
+    source: "extension",
+  });
+  await waitForSessionTurnSettlement(() => ({
+    isStreaming: runSession.isStreaming,
+    pendingMessageCount: runSession.pendingMessageCount,
+  }));
+}
 
 export async function renameSessionFile(
   cwd: string,

package/gui/server/shutdown.ts

@@ -0,0 +1,47 @@
+import type { Server } from "node:http";
+
+type Cleanup = () => void | Promise<void>;
+
+export interface GracefulShutdownOptions {
+  server: Server;
+  cleanup: Cleanup;
+  exit: (code: number) => void;
+  timeoutMs?: number;
+}
+
+export function createGracefulShutdown({
+  server,
+  cleanup,
+  exit,
+  timeoutMs = 1000,
+}: GracefulShutdownOptions): () => void {
+  let shuttingDown = false;
+  let exited = false;
+
+  const finish = () => {
+    if (exited) return;
+    exited = true;
+    exit(0);
+  };
+
+  return () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    const timeout = setTimeout(() => {
+      server.closeAllConnections?.();
+      finish();
+    }, timeoutMs);
+    timeout.unref?.();
+
+    void Promise.resolve()
+      .then(cleanup)
+      .catch(() => undefined)
+      .finally(() => {
+        server.close(() => {
+          clearTimeout(timeout);
+          finish();
+        });
+      });
+  };
+}

package/gui/server/tool-invoke-ack.ts

@@ -0,0 +1,49 @@
+import type { InvokeToolResult } from "./invoke-tool.js";
+
+export interface ToolInvokeAckMessage {
+  type: "tool.invoke.result";
+  requestId: string;
+  ok: boolean;
+  toolName: string;
+  result?: {
+    toolCallId: string;
+    content: InvokeToolResult["result"]["content"];
+    details: unknown;
+    isError: boolean;
+  };
+  error?: {
+    message: string;
+  };
+}
+
+export function buildToolInvokeAckMessage(
+  requestId: string,
+  toolName: string,
+  invocation: InvokeToolResult,
+): ToolInvokeAckMessage {
+  const message: ToolInvokeAckMessage = {
+    type: "tool.invoke.result",
+    requestId,
+    ok: !invocation.isError,
+    toolName,
+    result: {
+      toolCallId: invocation.toolCallId,
+      content: invocation.result.content,
+      details: invocation.result.details,
+      isError: invocation.isError,
+    },
+  };
+  if (invocation.isError) {
+    message.error = { message: toolResultMessage(invocation) };
+  }
+  return message;
+}
+
+function toolResultMessage(invocation: InvokeToolResult): string {
+  for (const item of invocation.result.content) {
+    if (item?.type === "text" && typeof item.text === "string" && item.text.trim()) {
+      return item.text.trim();
+    }
+  }
+  return `${invocation.toolCallId} failed`;
+}

package/gui/server/tool-metadata.ts

@@ -1,6 +1,6 @@
 import { getOpenCandleToolDefinitions } from "../../src/index.js";
-import { PROVIDERS, getCredential } from "../../src/onboarding/providers.js";
 import { getAllDefaults, setDefault } from "../../src/memory/tool-defaults.js";
+import { getCredential, PROVIDERS } from "../../src/onboarding/providers.js";
 
 const WORKFLOWS = [
   {
@@ -56,12 +56,7 @@ export function buildCatalog() {
         displayName: provider.displayName,
         source,
         apiKey: credential.value,
-        status:
-          source === "env"
-            ? "From env"
-            : source === "file"
-              ? "Configured"
-              : "Not configured",
+        status: source === "env" ? "From env" : source === "file" ? "Configured" : "Not configured",
         unlocks: provider.unlocks,
         fallbackDescription: provider.fallbackDescription,
         signupUrl: provider.signupUrl,
@@ -78,11 +73,29 @@ export function setToolEnabled(toolName: string, enabled: boolean): void {
 
 function inferDomain(toolName: string): string {
   if (toolName.includes("option")) return "options";
-  if (toolName.includes("portfolio") || toolName.includes("risk") || toolName.includes("correlation")) return "portfolio";
-  if (toolName.includes("sentiment") || toolName.includes("reddit") || toolName.includes("twitter") || toolName.includes("web")) return "sentiment";
+  if (
+    toolName.includes("portfolio") ||
+    toolName.includes("risk") ||
+    toolName.includes("correlation")
+  )
+    return "portfolio";
+  if (
+    toolName.includes("sentiment") ||
+    toolName.includes("reddit") ||
+    toolName.includes("twitter") ||
+    toolName.includes("web")
+  )
+    return "sentiment";
   if (toolName.includes("economic") || toolName.includes("fear")) return "macro";
   if (toolName.includes("technical") || toolName.includes("backtest")) return "technical";
-  if (toolName.includes("company") || toolName.includes("financial") || toolName.includes("earnings") || toolName.includes("dcf") || toolName.includes("sec")) return "fundamentals";
+  if (
+    toolName.includes("company") ||
+    toolName.includes("financial") ||
+    toolName.includes("earnings") ||
+    toolName.includes("dcf") ||
+    toolName.includes("sec")
+  )
+    return "fundamentals";
   if (toolName.includes("ask_user") || toolName.includes("login")) return "interaction";
   return "market";
 }

package/gui/server/websocket.ts

@@ -48,15 +48,25 @@ export function acceptWebSocket(req: IncomingMessage, socket: Duplex): WsClient
       if (frame.opcode !== 1) continue;
       try {
         const parsed = JSON.parse(frame.payload.toString("utf8"));
-        messageHandlers.forEach((handler) => handler(parsed));
+        for (const handler of messageHandlers) {
+          handler(parsed);
+        }
       } catch {
         // Ignore malformed client frames; the GUI reconnects on protocol errors.
       }
     }
   });
 
-  socket.on("close", () => closeHandlers.forEach((handler) => handler()));
-  socket.on("error", () => closeHandlers.forEach((handler) => handler()));
+  socket.on("close", () => {
+    for (const handler of closeHandlers) {
+      handler();
+    }
+  });
+  socket.on("error", () => {
+    for (const handler of closeHandlers) {
+      handler();
+    }
+  });
 
   return {
     send(data) {

package/gui/server/writer-lock.ts

@@ -53,7 +53,9 @@ export async function acquireWriterLock(
   const recovered = tryCreate(sessionDir, processKind, pid);
   if (recovered) return { role: "writer", lock: recovered };
 
-  return { role: "follower", lock: readWriterLock(sessionDir) ?? afterGrace ?? existing! };
+  const current = readWriterLock(sessionDir) ?? afterGrace ?? existing;
+  if (!current) throw new Error("Unable to determine active writer lock");
+  return { role: "follower", lock: current };
 }
 
 export function readWriterLock(sessionDir: string): WriterLock | null {
@@ -106,7 +108,9 @@ function isPidAlive(pid: number): boolean {
 
 function isLockCurrent(lock: WriterLock, staleGraceMs: number): boolean {
   const heartbeat = Date.parse(lock.lastHeartbeat);
-  return isPidAlive(lock.pid) && Number.isFinite(heartbeat) && Date.now() - heartbeat <= staleGraceMs;
+  return (
+    isPidAlive(lock.pid) && Number.isFinite(heartbeat) && Date.now() - heartbeat <= staleGraceMs
+  );
 }
 
 function lockPath(sessionDir: string): string {

package/gui/server/ws-hub.ts

@@ -0,0 +1,292 @@
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import {
+  type AgentSession,
+  type SessionEntry,
+  SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import type { ChatEvent } from "../shared/chat-events.js";
+import type { BackgroundQuoteRefreshes } from "./background-quotes.js";
+import { sessionEntriesToChatEvents } from "./chat-event-adapter.js";
+import type { ToolInvokeController } from "./invoke-tool.js";
+import type { ModelSetupController } from "./model-setup.js";
+import { projectDashboard } from "./projector.js";
+import type { SessionActionsController } from "./session-actions.js";
+import { buildCatalog, setToolEnabled } from "./tool-metadata.js";
+import { acceptWebSocket, type WsClient } from "./websocket.js";
+
+interface AskUserBridge {
+  getPrompts(): unknown[];
+}
+
+export interface WsHub {
+  handleUpgrade(req: IncomingMessage, socket: Duplex): void;
+  getClientCount(): number;
+  closeClients(): void;
+  sendBoot(client: WsClient): void;
+  buildBootstrapPayload(): Promise<Record<string, unknown>>;
+  broadcast(message: unknown): void;
+  broadcastModelSetup(): void;
+  broadcastState(): void;
+  broadcastSessions(): void;
+  buildStateSnapshot(): {
+    sessionId: string;
+    state: unknown;
+    entries: SessionEntry[];
+    events: ChatEvent[];
+  };
+  currentChatEvents(entries?: SessionEntry[]): ChatEvent[];
+  subscribeToSessionEvents(): () => void;
+}
+
+export interface WsHubOptions {
+  role: string;
+  lock: unknown;
+  cwd: string;
+  sessionDir: string;
+  getSession: () => AgentSession;
+  getSessionManager: () => SessionManager;
+  backgroundQuoteRefreshes: BackgroundQuoteRefreshes;
+  askUserBridge: AskUserBridge;
+  modelSetupController: ModelSetupController;
+  toolInvokeController: ToolInvokeController;
+  sessionActionsController: SessionActionsController;
+  onClientCountChanged: () => void;
+  isTrustedRequest?: (req: IncomingMessage) => boolean;
+  acceptWebSocketFn?: typeof acceptWebSocket;
+}
+
+export function createWsHub({
+  role,
+  lock,
+  cwd,
+  sessionDir,
+  getSession,
+  getSessionManager,
+  backgroundQuoteRefreshes,
+  askUserBridge,
+  modelSetupController,
+  toolInvokeController,
+  sessionActionsController,
+  onClientCountChanged,
+  isTrustedRequest = () => true,
+  acceptWebSocketFn = acceptWebSocket,
+}: WsHubOptions): WsHub {
+  const clients = new Set<WsClient>();
+
+  function handleUpgrade(req: IncomingMessage, socket: Duplex): void {
+    if (req.url !== "/ws") {
+      socket.destroy();
+      return;
+    }
+    if (!isTrustedRequest(req)) {
+      socket.destroy();
+      return;
+    }
+
+    const client = acceptWebSocketFn(req, socket);
+    clients.add(client);
+    client.onClose(() => {
+      clients.delete(client);
+      onClientCountChanged();
+    });
+    client.onMessage((message) => void handleClientMessage(client, message));
+    sendBoot(client);
+    onClientCountChanged();
+  }
+
+  async function handleClientMessage(client: WsClient, message: unknown): Promise<void> {
+    const data = asRecord(message);
+    try {
+      switch (data.type) {
+        case "chat.prompt":
+          await sessionActionsController.handlePrompt(String(data.prompt ?? ""));
+          break;
+        case "ask_user.answer":
+          await sessionActionsController.handleAskUserAnswer(String(data.id ?? ""), data.answer);
+          break;
+        case "ask_user.cancel":
+          await sessionActionsController.handleAskUserCancel(String(data.id ?? ""));
+          break;
+        case "tool.invoke":
+          await toolInvokeController.handleToolInvokeMessage(client, data);
+          break;
+        case "tool.enabled":
+          if (role !== "writer") throw new Error("Read-only follower mode");
+          setToolEnabled(String(data.toolName), Boolean(data.enabled));
+          broadcast({ type: "catalog", catalog: buildCatalog(), restartRequired: true });
+          break;
+        case "catalog.refresh":
+          client.send({ type: "catalog", catalog: buildCatalog() });
+          break;
+        case "model.setup.refresh":
+          getSession().modelRegistry.refresh();
+          broadcastModelSetup();
+          break;
+        case "model.setup.save_api_key":
+          await modelSetupController.handleSaveModelApiKey(
+            String(data.provider ?? ""),
+            String(data.apiKey ?? ""),
+          );
+          broadcastModelSetup();
+          break;
+        case "model.setup.select_model":
+          await modelSetupController.handleSelectModel(
+            String(data.provider ?? ""),
+            String(data.modelId ?? ""),
+          );
+          broadcastModelSetup();
+          break;
+        case "provider.save_api_key":
+          await modelSetupController.handleSaveProviderApiKey(
+            String(data.providerId ?? ""),
+            String(data.apiKey ?? ""),
+          );
+          broadcast({ type: "catalog", catalog: buildCatalog() });
+          break;
+        case "session.new":
+          await sessionActionsController.handleNewSession();
+          sendBoot(client);
+          broadcastState();
+          broadcastSessions();
+          break;
+        case "session.open":
+          await sessionActionsController.handleOpenSession(String(data.path ?? ""));
+          sendBoot(client);
+          broadcastState();
+          broadcastSessions();
+          break;
+        case "session.rename":
+          await sessionActionsController.handleRenameSession(
+            String(data.path ?? ""),
+            String(data.name ?? ""),
+          );
+          broadcastState();
+          broadcastSessions();
+          break;
+        case "session.delete":
+          await sessionActionsController.handleDeleteSession(client, String(data.path ?? ""));
+          break;
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      client.send({
+        type: "error",
+        message: errorMessage,
+      });
+    }
+  }
+
+  function getClientCount(): number {
+    return clients.size;
+  }
+
+  function closeClients(): void {
+    for (const client of clients) client.close();
+    clients.clear();
+  }
+
+  function sendBoot(client: WsClient): void {
+    const snapshot = buildStateSnapshot();
+    client.send({
+      type: "boot",
+      role,
+      lock,
+      sessionId: getSessionManager().getSessionId(),
+      catalog: buildCatalog(),
+      modelSetup: modelSetupController.buildCurrentModelSetupState(),
+      askUserPrompts: askUserBridge.getPrompts(),
+    });
+    client.send({
+      type: "state.snapshot",
+      ...snapshot,
+    });
+    void SessionManager.list(cwd, sessionDir).then((sessions) =>
+      client.send({ type: "sessions", sessions }),
+    );
+  }
+
+  async function buildBootstrapPayload(): Promise<Record<string, unknown>> {
+    return {
+      role,
+      sessionId: getSessionManager().getSessionId(),
+      catalog: buildCatalog(),
+      modelSetup: modelSetupController.buildCurrentModelSetupState(),
+      askUserPrompts: askUserBridge.getPrompts(),
+      sessions: await SessionManager.list(cwd, sessionDir),
+      snapshot: buildStateSnapshot(),
+    };
+  }
+
+  function broadcastModelSetup(): void {
+    broadcast({
+      type: "model.setup",
+      modelSetup: modelSetupController.buildCurrentModelSetupState(),
+    });
+  }
+
+  function broadcastState(): void {
+    broadcast({
+      type: "state.snapshot",
+      ...buildStateSnapshot(),
+    });
+  }
+
+  function buildStateSnapshot() {
+    const sessionManager = getSessionManager();
+    const sessionId = sessionManager.getSessionId();
+    const entries = sessionManager.getEntries();
+    return {
+      sessionId,
+      state: projectDashboard(backgroundQuoteRefreshes.withEntries(entries), sessionId),
+      entries,
+      events: currentChatEvents(entries),
+    };
+  }
+
+  function currentChatEvents(entries = getSessionManager().getEntries()): ChatEvent[] {
+    const sessionManager = getSessionManager();
+    return sessionEntriesToChatEvents(entries, {
+      sessionId: sessionManager.getSessionId(),
+      title: sessionManager.getSessionName(),
+    });
+  }
+
+  function broadcastSessions(): void {
+    void SessionManager.list(cwd, sessionDir).then((sessions) =>
+      broadcast({ type: "sessions", sessions }),
+    );
+  }
+
+  function broadcast(message: unknown): void {
+    for (const client of clients) client.send(message);
+  }
+
+  function subscribeToSessionEvents(): () => void {
+    return getSession().subscribe((event) => {
+      broadcast({ type: "session.event", event });
+      broadcastState();
+    });
+  }
+
+  return {
+    handleUpgrade,
+    getClientCount,
+    closeClients,
+    sendBoot,
+    buildBootstrapPayload,
+    broadcast,
+    broadcastModelSetup,
+    broadcastState,
+    broadcastSessions,
+    buildStateSnapshot,
+    currentChatEvents,
+    subscribeToSessionEvents,
+  };
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}