opencandle 0.3.0 → 0.5.0

package/gui/server/invoke-tool.ts

@@ -0,0 +1,89 @@
+import type { AgentTool, AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Message, ToolCall, Usage } from "@earendil-works/pi-ai";
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { getDefaults } from "../../src/memory/tool-defaults.js";
+import { wrapWithDefaults } from "../../src/runtime/tool-defaults-wrapper.js";
+
+export interface InvokeToolResult {
+  toolCallId: string;
+  result: AgentToolResult<unknown>;
+  isError: boolean;
+}
+
+export async function invokeToolFromUi(
+  sessionManager: SessionManager,
+  tool: AgentTool<TSchema, unknown>,
+  args: Record<string, unknown>,
+  source: "ui" | "background" = "ui",
+  options: { recordTranscript?: boolean } = {},
+): Promise<InvokeToolResult> {
+  if (!Value.Check(tool.parameters, args)) {
+    const errors = [...Value.Errors(tool.parameters, args)]
+      .map((error) => `${error.path || "/"} ${error.message}`)
+      .join("; ");
+    throw new Error(errors || "Invalid tool arguments");
+  }
+
+  const toolCallId = `${source}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const call: ToolCall = {
+    type: "toolCall",
+    id: toolCallId,
+    name: tool.name,
+    arguments: args,
+  };
+  const assistant = {
+    role: "assistant",
+    content: [call],
+    api: "openai-responses",
+    provider: "openai",
+    model: "ui-direct",
+    usage: emptyUsage(),
+    stopReason: "toolUse",
+    timestamp: Date.now(),
+  } satisfies Message;
+
+  const recordTranscript = options.recordTranscript ?? true;
+  if (recordTranscript) {
+    sessionManager.appendMessage(assistant);
+  }
+
+  const wrapped = wrapWithDefaults(tool, getDefaults(tool.name));
+  let result: AgentToolResult<unknown>;
+  let isError = false;
+  try {
+    result = await wrapped.execute(toolCallId, args as never);
+  } catch (error) {
+    isError = true;
+    result = {
+      content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+      details: null,
+    };
+  }
+
+  if (recordTranscript) {
+    sessionManager.appendMessage({
+      role: "toolResult",
+      toolCallId,
+      toolName: tool.name,
+      content: result.content,
+      details: { source, args, value: result.details },
+      isError,
+      timestamp: Date.now(),
+    });
+  }
+
+  return { toolCallId, result, isError };
+}
+
+function emptyUsage(): Usage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+}

package/gui/server/live-chat-event-adapter.ts

@@ -0,0 +1,181 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { AssistantMessage, Message } from "@earendil-works/pi-ai";
+import type { ChatEvent, MessageContent, ToolOutput } from "../shared/chat-events.js";
+
+export interface LiveChatEventAdapterOptions {
+  runId: string;
+  sessionId: string;
+  startSeq: number;
+  emit: (event: ChatEvent) => void;
+}
+
+export interface LiveChatEventAdapter {
+  handle(event: AgentSessionEvent): void;
+  nextSeq(): number;
+}
+
+export function createLiveChatEventAdapter(options: LiveChatEventAdapterOptions): LiveChatEventAdapter {
+  let seq = options.startSeq;
+  let userCount = 0;
+  let assistantCount = 0;
+  let currentAssistantMessageId: string | undefined;
+  let lastAssistantMessageId: string | undefined;
+  const completedMessageIds = new Set<string>();
+
+  const emit = (event: Omit<ChatEvent, "seq">) => {
+    options.emit({ ...event, seq: seq++ } as ChatEvent);
+  };
+
+  const ensureAssistantMessage = (): string => {
+    if (currentAssistantMessageId) return currentAssistantMessageId;
+    currentAssistantMessageId = `${options.runId}-assistant-${++assistantCount}`;
+    lastAssistantMessageId = currentAssistantMessageId;
+    emit({ type: "message.created", messageId: currentAssistantMessageId, role: "assistant" });
+    return currentAssistantMessageId;
+  };
+
+  const messageIdForTool = (): string => lastAssistantMessageId ?? ensureAssistantMessage();
+
+  const completeAssistantMessage = (message: AssistantMessage) => {
+    const messageId = ensureAssistantMessage();
+    if (completedMessageIds.has(messageId)) return;
+    completedMessageIds.add(messageId);
+    emit({
+      type: "message.completed",
+      messageId,
+      content: contentToChatContent(message.content),
+    });
+    currentAssistantMessageId = undefined;
+  };
+
+  return {
+    handle(event) {
+      switch (event.type) {
+        case "message_start": {
+          const message = event.message as Message;
+          if (message.role === "user") {
+            const messageId = `${options.runId}-user-${++userCount}`;
+            emit({ type: "message.created", messageId, role: "user" });
+            emit({
+              type: "message.completed",
+              messageId,
+              content: [{ type: "text", text: messageText(message.content) }],
+            });
+            return;
+          }
+          if (message.role === "assistant") {
+            ensureAssistantMessage();
+          }
+          return;
+        }
+
+        case "message_update": {
+          const update = event.assistantMessageEvent;
+          if (update.type === "text_delta") {
+            emit({
+              type: "message.delta",
+              messageId: ensureAssistantMessage(),
+              text: update.delta,
+            });
+          }
+          if (update.type === "thinking_delta") {
+            emit({
+              type: "thinking.delta",
+              runId: options.runId,
+              text: update.delta,
+            });
+          }
+          if (update.type === "thinking_end") {
+            emit({
+              type: "thinking.completed",
+              runId: options.runId,
+              text: update.content,
+            });
+          }
+          return;
+        }
+
+        case "message_end": {
+          const message = event.message as Message;
+          if (message.role === "assistant") completeAssistantMessage(message);
+          return;
+        }
+
+        case "tool_execution_start": {
+          const messageId = messageIdForTool();
+          emit({
+            type: "tool.started",
+            toolCallId: event.toolCallId,
+            messageId,
+            name: event.toolName,
+            input: event.args,
+          });
+          return;
+        }
+
+        case "tool_execution_update":
+          emit({
+            type: "tool.delta",
+            toolCallId: event.toolCallId,
+            chunk: event.partialResult,
+          });
+          return;
+
+        case "tool_execution_end": {
+          const output = toolOutput(event.result, event.isError);
+          if (event.isError) {
+            emit({
+              type: "tool.failed",
+              toolCallId: event.toolCallId,
+              error: {
+                message: messageText(output.content),
+                details: output.details,
+              },
+            });
+          } else {
+            emit({
+              type: "tool.completed",
+              toolCallId: event.toolCallId,
+              output,
+            });
+          }
+          return;
+        }
+      }
+    },
+    nextSeq() {
+      return seq;
+    },
+  };
+}
+
+function contentToChatContent(content: AssistantMessage["content"]): MessageContent[] {
+  return content.flatMap((part): MessageContent[] => {
+    if (part.type === "text") return [{ type: "text", text: part.text }];
+    if (part.type === "toolCall") return [{ type: "tool", toolCallId: part.id }];
+    return [];
+  });
+}
+
+function messageText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => typeof part === "object" && part !== null && "text" in part && typeof part.text === "string" ? part.text : "")
+    .join("");
+}
+
+function toolOutput(result: unknown, isError: boolean): ToolOutput {
+  const record = asRecord(result);
+  return {
+    content: Array.isArray(record.content) ? record.content as ToolOutput["content"] : [],
+    details: record.details,
+    isError,
+  };
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}

package/gui/server/model-setup.ts

@@ -0,0 +1,100 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+
+export type ModelSetupRequirement = "ready" | "select_model" | "connect_auth";
+
+export interface ModelSetupProvider {
+  id: string;
+  label: string;
+  envVar: string;
+  defaultProvider: string;
+  defaultModel: string;
+  signupUrl: string;
+}
+
+export interface ModelSetupState {
+  requirement: ModelSetupRequirement;
+  currentModel?: string;
+  providers: ModelSetupProvider[];
+  availableModels: Array<{ provider: string; id: string; label: string }>;
+}
+
+export interface ModelSetupRegistry {
+  refresh(): void;
+  getAvailable(): Model<Api>[];
+  hasConfiguredAuth(model: Model<Api>): boolean;
+}
+
+export const modelSetupProviders: ModelSetupProvider[] = [
+  {
+    id: "google",
+    label: "Google Gemini",
+    envVar: "GEMINI_API_KEY",
+    defaultProvider: "google",
+    defaultModel: "gemini-2.5-flash",
+    signupUrl: "https://aistudio.google.com/app/apikey",
+  },
+  {
+    id: "openai",
+    label: "OpenAI",
+    envVar: "OPENAI_API_KEY",
+    defaultProvider: "openai",
+    defaultModel: "gpt-5-mini",
+    signupUrl: "https://platform.openai.com/api-keys",
+  },
+  {
+    id: "anthropic",
+    label: "Anthropic",
+    envVar: "ANTHROPIC_API_KEY",
+    defaultProvider: "anthropic",
+    defaultModel: "claude-haiku-4-5",
+    signupUrl: "https://console.anthropic.com/settings/keys",
+  },
+];
+
+export function buildModelSetupState(
+  registry: ModelSetupRegistry,
+  currentModel: Model<Api> | undefined,
+): ModelSetupState {
+  registry.refresh();
+  const availableModels = sortModels(registry.getAvailable()).map((model) => ({
+    provider: model.provider,
+    id: model.id,
+    label: `${model.provider}/${model.id}`,
+  }));
+  const requirement =
+    currentModel && registry.hasConfiguredAuth(currentModel)
+      ? "ready"
+      : availableModels.length > 0
+        ? "select_model"
+        : "connect_auth";
+
+  return {
+    requirement,
+    currentModel: currentModel ? `${currentModel.provider}/${currentModel.id}` : undefined,
+    providers: modelSetupProviders,
+    availableModels,
+  };
+}
+
+export function findPreferredModel(
+  registry: Pick<ModelSetupRegistry, "getAvailable">,
+  provider: ModelSetupProvider,
+): Model<Api> | undefined {
+  const available = sortModels(registry.getAvailable(), provider.defaultProvider);
+  return (
+    available.find(
+      (model) =>
+        model.provider === provider.defaultProvider && model.id === provider.defaultModel,
+    ) ?? available.find((model) => model.provider === provider.defaultProvider)
+  );
+}
+
+export function sortModels(models: Model<Api>[], preferredProvider?: string): Model<Api>[] {
+  return [...models].sort((a, b) => {
+    const aPreferred = preferredProvider && a.provider === preferredProvider ? -1 : 0;
+    const bPreferred = preferredProvider && b.provider === preferredProvider ? -1 : 0;
+    if (aPreferred !== bPreferred) return aPreferred - bPreferred;
+    const byProvider = a.provider.localeCompare(b.provider);
+    return byProvider !== 0 ? byProvider : a.id.localeCompare(b.id);
+  });
+}

package/gui/server/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@opencandle/gui-server",
+  "private": true,
+  "type": "module"
+}

package/gui/server/projector.ts

@@ -0,0 +1,254 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { Message, ToolResultMessage } from "@earendil-works/pi-ai";
+
+export interface DashboardState {
+  watchlist: Array<{
+    symbol: string;
+    quote: Record<string, unknown> | null;
+    pinned: boolean;
+    lastSeen: string;
+  }>;
+  activeAnalyses: Array<{
+    workflowId: string;
+    workflow: string;
+    symbol?: string;
+    analystsTotal: number;
+    analystsDone: number;
+    startedAt: string;
+  }>;
+  recentResearch: Array<{
+    sessionId: string;
+    workflow: string;
+    symbol?: string;
+    completedAt: string;
+  }>;
+  dataQuality: {
+    softGaps: Array<{ provider: string; lastSeen: string }>;
+    hardSkips: Array<{ provider: string; lastSeen: string }>;
+  };
+}
+
+const DIRECT_TOOL_GAP_PROVIDERS: Record<string, string> = {
+  get_company_overview: "alpha_vantage",
+  get_financials: "alpha_vantage",
+  get_earnings: "alpha_vantage",
+  compute_dcf: "alpha_vantage",
+  compare_companies: "alpha_vantage",
+  get_economic_data: "fred",
+  get_twitter_sentiment: "twitter",
+};
+
+export function createEmptyDashboardState(): DashboardState {
+  return {
+    watchlist: [],
+    activeAnalyses: [],
+    recentResearch: [],
+    dataQuality: { softGaps: [], hardSkips: [] },
+  };
+}
+
+export function projectDashboard(entries: SessionEntry[], sessionId = "local"): DashboardState {
+  const state = createEmptyDashboardState();
+
+  for (const entry of entries) {
+    if (entry.type === "message") {
+      projectMessage(state, entry.message as Message, entry.timestamp, sessionId);
+      continue;
+    }
+
+    if (entry.type === "custom" && entry.customType === "opencandle-workflow") {
+      const data = asRecord(entry.data);
+      const workflow = stringValue(data.workflow) ?? stringValue(data.workflowType) ?? "workflow";
+      const slots = asRecord(data.resolvedSlots);
+      const symbol = stringValue(slots.symbol) ?? firstString(slots.symbols);
+      state.activeAnalyses.push({
+        workflowId: stringValue(data.runId) ?? entry.id,
+        workflow,
+        symbol,
+        analystsTotal: numberValue(data.analystsTotal) ?? 0,
+        analystsDone: 0,
+        startedAt: entry.timestamp,
+      });
+      continue;
+    }
+
+    if (entry.type === "custom" && entry.customType === "opencandle-turn-gap") {
+      // The accumulator writes a single combined annotation string with one
+      // [OPENCANDLE_SKIPPED ... provider=X ...] tag per fallback provider.
+      // Older shapes may carry { softGaps: [...] } or { provider } directly —
+      // accept either to stay forward/backward compatible.
+      const data = asRecord(entry.data);
+      const annotation = stringValue(data.annotation);
+      if (annotation) {
+        for (const provider of parseSkippedProviders(annotation)) {
+          upsertProviderGap(state.dataQuality.softGaps, provider, entry.timestamp);
+        }
+      }
+      for (const gap of asArray(data.softGaps)) {
+        const provider = stringValue(asRecord(gap).provider);
+        if (provider) upsertProviderGap(state.dataQuality.softGaps, provider, entry.timestamp);
+      }
+      const provider = stringValue(data.provider);
+      if (provider) upsertProviderGap(state.dataQuality.softGaps, provider, entry.timestamp);
+    }
+
+    if (entry.type === "custom" && entry.customType === "opencandle-quote-refresh") {
+      const data = asRecord(entry.data);
+      projectQuote(
+        state,
+        stringValue(data.symbol),
+        asRecord(data.value),
+        asArray(data.content) as ToolResultMessage["content"],
+        entry.timestamp,
+      );
+    }
+  }
+
+  return state;
+}
+
+function projectMessage(
+  state: DashboardState,
+  message: Message,
+  timestamp: string,
+  sessionId: string,
+): void {
+  if (message.role === "toolResult") {
+    projectToolResult(state, message, timestamp);
+    return;
+  }
+
+  if (message.role === "assistant" && message.stopReason === "stop") {
+    const active = state.activeAnalyses.shift();
+    if (active) {
+      state.recentResearch.unshift({
+        sessionId,
+        workflow: active.workflow,
+        symbol: active.symbol,
+        completedAt: timestamp,
+      });
+    }
+  }
+}
+
+function projectToolResult(
+  state: DashboardState,
+  message: ToolResultMessage,
+  timestamp: string,
+): void {
+  if (message.toolName === "get_stock_quote") {
+    const rawDetails = asRecord(message.details);
+    const nestedValue = asRecord(rawDetails.value);
+    const details = Object.keys(nestedValue).length > 0 ? nestedValue : rawDetails;
+    projectQuote(state, stringValue(details.symbol), details, message.content, timestamp);
+  }
+
+  const text = message.content
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("\n");
+  for (const provider of parseSoftGapProviders(text)) {
+    upsertProviderGap(state.dataQuality.softGaps, provider, timestamp);
+  }
+  for (const provider of parseCredentialRequiredProviders(text)) {
+    upsertProviderGap(state.dataQuality.hardSkips, provider, timestamp);
+  }
+  const provider = inferDirectToolGapProvider(message.toolName, text);
+  if (provider) upsertProviderGap(state.dataQuality.softGaps, provider, timestamp);
+}
+
+function upsertProviderGap(
+  gaps: Array<{ provider: string; lastSeen: string }>,
+  provider: string,
+  lastSeen: string,
+): void {
+  const existing = gaps.find((gap) => gap.provider === provider);
+  if (!existing) {
+    gaps.push({ provider, lastSeen });
+    return;
+  }
+
+  const existingTime = Date.parse(existing.lastSeen);
+  const nextTime = Date.parse(lastSeen);
+  if (!Number.isFinite(existingTime) || (Number.isFinite(nextTime) && nextTime > existingTime)) {
+    existing.lastSeen = lastSeen;
+  }
+}
+
+function projectQuote(
+  state: DashboardState,
+  symbolHint: string | undefined,
+  details: Record<string, unknown>,
+  content: ToolResultMessage["content"],
+  timestamp: string,
+): void {
+  const symbol = symbolHint ?? inferSymbolFromContent(content);
+  if (!symbol) return;
+
+  const existing = state.watchlist.find((row) => row.symbol === symbol);
+  const row = {
+    symbol,
+    quote: Object.keys(details).length > 0 ? details : null,
+    pinned: existing?.pinned ?? false,
+    lastSeen: timestamp,
+  };
+  if (existing) Object.assign(existing, row);
+  else state.watchlist.push(row);
+}
+
+function parseCredentialRequiredProviders(text: string): string[] {
+  const providers: string[] = [];
+  const re = /\[OPENCANDLE_CREDENTIAL_REQUIRED[^\]]*provider=([a-z0-9_-]+)/gi;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(text)) !== null) {
+    providers.push(match[1]);
+  }
+  return providers;
+}
+
+function parseSkippedProviders(text: string): string[] {
+  return parseSoftGapProviders(text);
+}
+
+function parseSoftGapProviders(text: string): string[] {
+  const providers: string[] = [];
+  const re = /\[OPENCANDLE_(?:SKIPPED|SOFT_DEGRADED)[^\]]*provider=([a-z0-9_-]+)/gi;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(text)) !== null) {
+    providers.push(match[1]);
+  }
+  return providers;
+}
+
+function inferDirectToolGapProvider(toolName: string | undefined, text: string): string | undefined {
+  if (!toolName || !/(?:⚠|unavailable|No .*data found|LOGIN_NEEDED)/i.test(text)) return undefined;
+  return DIRECT_TOOL_GAP_PROVIDERS[toolName];
+}
+
+function inferSymbolFromContent(content: ToolResultMessage["content"]): string | undefined {
+  const text = content.find((part) => part.type === "text")?.text;
+  const match = text?.match(/^([A-Z]{1,8})\b/);
+  return match?.[1];
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function firstString(value: unknown): string | undefined {
+  return Array.isArray(value) ? value.find((item) => typeof item === "string") : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" ? value : undefined;
+}

package/gui/server/prompt-observation.ts

@@ -0,0 +1,61 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+
+export interface PromptObservation {
+  userTexts: string[];
+  sawAssistantOrTool: boolean;
+}
+
+export function createPromptObservation(): PromptObservation {
+  return {
+    userTexts: [],
+    sawAssistantOrTool: false,
+  };
+}
+
+export function observePromptEvent(observation: PromptObservation, event: AgentSessionEvent): void {
+  if (event.type === "message_start") {
+    const message = event.message as { role?: unknown; content?: unknown };
+    if (message.role === "user") {
+      observation.userTexts.push(messageTextFromContent(message.content));
+      return;
+    }
+    if (message.role === "assistant") {
+      observation.sawAssistantOrTool = true;
+    }
+    return;
+  }
+
+  if (event.type === "tool_execution_start") {
+    observation.sawAssistantOrTool = true;
+  }
+}
+
+export function selectReplayPrompt(
+  observation: PromptObservation,
+  originalPrompt: string,
+): string | undefined {
+  if (observation.sawAssistantOrTool) return undefined;
+
+  const original = originalPrompt.trim();
+  const text = [...observation.userTexts]
+    .reverse()
+    .map((candidate) => candidate.trim())
+    .find((candidate) => candidate.length > 0 && candidate !== original);
+
+  return text || undefined;
+}
+
+function messageTextFromContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => (
+      typeof part === "object" &&
+        part !== null &&
+        "text" in part &&
+        typeof part.text === "string"
+        ? part.text
+        : ""
+    ))
+    .join("");
+}