@axhub/genie 0.1.8 → 0.2.0

package/server/session-core/runtimeState.js

@@ -0,0 +1,390 @@
+import {
+  CONVERSATION_EVENT_KINDS,
+  SUPPORTED_PROVIDERS
+} from '../../shared/conversationEvents.js';
+import {
+  mergeConversationEventHistories
+} from './eventStore.js';
+import { getProviderAdapter } from './providerAdapters.js';
+import { getProjects } from '../projects.js';
+import { isClaudeSDKSessionActive } from '../claude-sdk.js';
+import { isCodexSessionActive } from '../openai-codex.js';
+import { isGeminiSessionActive } from '../gemini-cli.js';
+import { isOpencodeSessionActive } from '../opencode-cli.js';
+
+export const AGENT_RUNTIME_PHASES = {
+  IDLE: 'idle',
+  QUEUED: 'queued',
+  STREAMING: 'streaming',
+  AWAITING_APPROVAL: 'awaiting_approval',
+  COMPLETED: 'completed',
+  ABORTED: 'aborted',
+  ERRORED: 'errored'
+};
+
+const ACTIVE_PHASES = new Set([
+  AGENT_RUNTIME_PHASES.QUEUED,
+  AGENT_RUNTIME_PHASES.STREAMING,
+  AGENT_RUNTIME_PHASES.AWAITING_APPROVAL
+]);
+const TERMINAL_PHASES = new Set([
+  AGENT_RUNTIME_PHASES.COMPLETED,
+  AGENT_RUNTIME_PHASES.ABORTED,
+  AGENT_RUNTIME_PHASES.ERRORED
+]);
+const sessionRuntimeListeners = new Set();
+const lastBroadcastSignatures = new Map();
+
+function normalizeNonEmptyString(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const normalized = value.trim();
+  return normalized ? normalized : null;
+}
+
+function normalizeProvider(provider) {
+  const normalized = normalizeNonEmptyString(provider)?.toLowerCase() || null;
+  return SUPPORTED_PROVIDERS.includes(normalized) ? normalized : null;
+}
+
+function normalizePhase(phase) {
+  const normalized = normalizeNonEmptyString(phase)?.toLowerCase() || null;
+  return Object.values(AGENT_RUNTIME_PHASES).includes(normalized) ? normalized : null;
+}
+
+function getProviderProjectSessions(project, provider) {
+  if (!project || typeof project !== 'object') {
+    return [];
+  }
+
+  if (provider === 'claude') {
+    return Array.isArray(project.sessions) ? project.sessions : [];
+  }
+
+  if (provider === 'codex') {
+    return Array.isArray(project.codexSessions) ? project.codexSessions : [];
+  }
+
+  if (provider === 'gemini') {
+    return Array.isArray(project.geminiSessions) ? project.geminiSessions : [];
+  }
+
+  if (provider === 'opencode') {
+    return Array.isArray(project.opencodeSessions) ? project.opencodeSessions : [];
+  }
+
+  return [];
+}
+
+async function resolveSessionProjectContext(provider, sessionId) {
+  const normalizedProvider = normalizeProvider(provider);
+  const normalizedSessionId = normalizeNonEmptyString(sessionId);
+
+  if (!normalizedProvider || !normalizedSessionId) {
+    return null;
+  }
+
+  const projects = await getProjects();
+
+  for (const project of projects) {
+    const sessions = getProviderProjectSessions(project, normalizedProvider);
+    const matchedSession = sessions.find((session) => session?.id === normalizedSessionId);
+    if (!matchedSession) {
+      continue;
+    }
+
+    return {
+      projectName: project.name,
+      projectPath: project.fullPath || project.path || null,
+      session: matchedSession
+    };
+  }
+
+  return null;
+}
+
+async function loadProviderEvents(provider, sessionId) {
+  const normalizedProvider = normalizeProvider(provider);
+  const normalizedSessionId = normalizeNonEmptyString(sessionId);
+
+  if (!normalizedProvider || !normalizedSessionId) {
+    return { events: [], context: null, error: null };
+  }
+
+  const adapter = getProviderAdapter(normalizedProvider);
+  const context = await resolveSessionProjectContext(normalizedProvider, normalizedSessionId);
+
+  try {
+    const result = await adapter.loadEvents({
+      projectName: context?.projectName,
+      projectPath: context?.projectPath,
+      sessionId: normalizedSessionId,
+      limit: null,
+      offset: 0
+    });
+
+    const events = Array.isArray(result) ? result : (Array.isArray(result?.events) ? result.events : []);
+
+    return {
+      events,
+      context,
+      error: null
+    };
+  } catch (error) {
+    return {
+      events: [],
+      context,
+      error
+    };
+  }
+}
+
+function isSessionActive(provider, sessionId) {
+  const normalizedProvider = normalizeProvider(provider);
+  const normalizedSessionId = normalizeNonEmptyString(sessionId);
+
+  if (!normalizedProvider || !normalizedSessionId) {
+    return false;
+  }
+
+  if (normalizedProvider === 'codex') {
+    return Boolean(isCodexSessionActive(normalizedSessionId));
+  }
+
+  if (normalizedProvider === 'gemini') {
+    return Boolean(isGeminiSessionActive(normalizedSessionId));
+  }
+
+  if (normalizedProvider === 'opencode') {
+    return Boolean(isOpencodeSessionActive(normalizedSessionId));
+  }
+
+  return Boolean(isClaudeSDKSessionActive(normalizedSessionId));
+}
+
+function inferPhaseFromEvents(events = []) {
+  let inferredPhase = null;
+
+  for (const event of events) {
+    if (!event || typeof event !== 'object') {
+      continue;
+    }
+
+    if (event.kind === CONVERSATION_EVENT_KINDS.ERROR) {
+      inferredPhase = AGENT_RUNTIME_PHASES.ERRORED;
+      continue;
+    }
+
+    if (event.kind === CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED) {
+      const nextPhase = normalizePhase(event.payload?.state);
+      if (nextPhase) {
+        inferredPhase = nextPhase;
+      }
+      continue;
+    }
+
+    if (event.kind === CONVERSATION_EVENT_KINDS.APPROVAL_REQUEST) {
+      inferredPhase = AGENT_RUNTIME_PHASES.AWAITING_APPROVAL;
+      continue;
+    }
+
+    if (event.kind === CONVERSATION_EVENT_KINDS.APPROVAL_RESOLVED) {
+      inferredPhase = AGENT_RUNTIME_PHASES.STREAMING;
+      continue;
+    }
+
+    if (
+      event.kind === CONVERSATION_EVENT_KINDS.ASSISTANT_TEXT_START ||
+      event.kind === CONVERSATION_EVENT_KINDS.ASSISTANT_TEXT_DELTA ||
+      event.kind === CONVERSATION_EVENT_KINDS.REASONING_START ||
+      event.kind === CONVERSATION_EVENT_KINDS.REASONING_DELTA ||
+      event.kind === CONVERSATION_EVENT_KINDS.TOOL_CALL_START ||
+      event.kind === CONVERSATION_EVENT_KINDS.TOOL_CALL_INPUT ||
+      event.kind === CONVERSATION_EVENT_KINDS.TOOL_CALL_END ||
+      event.kind === CONVERSATION_EVENT_KINDS.TOOL_RESULT ||
+      event.kind === CONVERSATION_EVENT_KINDS.SYSTEM_NOTICE
+    ) {
+      inferredPhase = AGENT_RUNTIME_PHASES.STREAMING;
+    }
+  }
+
+  return inferredPhase;
+}
+
+function inferPendingApproval(events = []) {
+  const pendingRequests = new Set();
+
+  for (const event of events) {
+    if (!event || typeof event !== 'object') {
+      continue;
+    }
+
+    const requestId = normalizeNonEmptyString(event.payload?.requestId) || normalizeNonEmptyString(event.extensions?.requestId);
+
+    if (event.kind === CONVERSATION_EVENT_KINDS.APPROVAL_REQUEST) {
+      if (requestId) {
+        pendingRequests.add(requestId);
+      }
+      continue;
+    }
+
+    if (event.kind === CONVERSATION_EVENT_KINDS.APPROVAL_RESOLVED) {
+      if (requestId) {
+        pendingRequests.delete(requestId);
+      }
+      continue;
+    }
+
+    if (event.kind === CONVERSATION_EVENT_KINDS.SESSION_STATE_CHANGED) {
+      const sessionState = normalizePhase(event.payload?.state);
+      if (
+        sessionState === AGENT_RUNTIME_PHASES.IDLE ||
+        sessionState === AGENT_RUNTIME_PHASES.COMPLETED ||
+        sessionState === AGENT_RUNTIME_PHASES.ABORTED ||
+        sessionState === AGENT_RUNTIME_PHASES.ERRORED
+      ) {
+        pendingRequests.clear();
+      }
+    }
+  }
+
+  return pendingRequests.size > 0;
+}
+
+function getLatestEventTimestamp(events = []) {
+  const latestEvent = [...events].reverse().find((event) => normalizeNonEmptyString(event?.timestamp));
+  return latestEvent?.timestamp || null;
+}
+
+function createRuntimeSignature(snapshot) {
+  return JSON.stringify({
+    phase: snapshot.phase,
+    isLoading: snapshot.isLoading,
+    canAbortSession: snapshot.canAbortSession,
+    hasPendingApproval: snapshot.hasPendingApproval
+  });
+}
+
+export function createSessionRuntimeSubscriptionKey(provider, sessionId) {
+  const normalizedProvider = normalizeProvider(provider);
+  const normalizedSessionId = normalizeNonEmptyString(sessionId);
+
+  if (!normalizedProvider || !normalizedSessionId) {
+    return null;
+  }
+
+  return `${normalizedProvider}:${normalizedSessionId}`;
+}
+
+export async function buildSessionRuntimeSnapshot(provider, sessionId, options = {}) {
+  const normalizedProvider = normalizeProvider(provider);
+  const normalizedSessionId = normalizeNonEmptyString(sessionId);
+
+  if (!normalizedProvider || !normalizedSessionId) {
+    return null;
+  }
+
+  const recentEvents = Array.isArray(options.recentEvents) ? options.recentEvents : [];
+  const { events: persistedEvents, context, error } = await loadProviderEvents(normalizedProvider, normalizedSessionId);
+  const mergedEvents = mergeConversationEventHistories(
+    persistedEvents,
+    recentEvents.filter((event) => event?.provider === normalizedProvider && event?.sessionId === normalizedSessionId)
+  );
+  const active = isSessionActive(normalizedProvider, normalizedSessionId);
+
+  const exists = active || Boolean(context) || mergedEvents.length > 0;
+  if (!exists) {
+    return null;
+  }
+
+  let phase = inferPhaseFromEvents(mergedEvents);
+  const hasPendingApproval = active ? inferPendingApproval(mergedEvents) : false;
+
+  if (TERMINAL_PHASES.has(phase)) {
+    // Keep terminal phase as-is.
+  } else if (hasPendingApproval) {
+    phase = AGENT_RUNTIME_PHASES.AWAITING_APPROVAL;
+  } else if (active) {
+    phase = ACTIVE_PHASES.has(phase) ? phase : AGENT_RUNTIME_PHASES.STREAMING;
+  } else {
+    phase = AGENT_RUNTIME_PHASES.IDLE;
+  }
+
+  const updatedAt = getLatestEventTimestamp(mergedEvents) || new Date().toISOString();
+
+  return {
+    sessionId: normalizedSessionId,
+    provider: normalizedProvider,
+    phase,
+    isLoading: active,
+    canAbortSession: active,
+    hasPendingApproval,
+    updatedAt,
+    _context: context,
+    _loadError: error || null
+  };
+}
+
+export function subscribeToSessionRuntimeStateChanges(listener) {
+  if (typeof listener !== 'function') {
+    return () => {};
+  }
+
+  sessionRuntimeListeners.add(listener);
+  return () => {
+    sessionRuntimeListeners.delete(listener);
+  };
+}
+
+export async function publishSessionRuntimeStateChanges(events = []) {
+  const groupedRecentEvents = new Map();
+
+  events.forEach((event) => {
+    const subscriptionKey = createSessionRuntimeSubscriptionKey(event?.provider, event?.sessionId);
+    if (!subscriptionKey) {
+      return;
+    }
+
+    if (!groupedRecentEvents.has(subscriptionKey)) {
+      groupedRecentEvents.set(subscriptionKey, []);
+    }
+
+    groupedRecentEvents.get(subscriptionKey).push(event);
+  });
+
+  await Promise.all(Array.from(groupedRecentEvents.entries()).map(async ([subscriptionKey, recentEvents]) => {
+    const [provider, sessionId] = subscriptionKey.split(':');
+    const snapshot = await buildSessionRuntimeSnapshot(provider, sessionId, { recentEvents });
+    if (!snapshot) {
+      return;
+    }
+
+    const signature = createRuntimeSignature(snapshot);
+    if (lastBroadcastSignatures.get(subscriptionKey) === signature) {
+      return;
+    }
+
+    lastBroadcastSignatures.set(subscriptionKey, signature);
+
+    sessionRuntimeListeners.forEach((listener) => {
+      try {
+        listener({
+          subscriptionKey,
+          snapshot: {
+            sessionId: snapshot.sessionId,
+            provider: snapshot.provider,
+            phase: snapshot.phase,
+            isLoading: snapshot.isLoading,
+            canAbortSession: snapshot.canAbortSession,
+            hasPendingApproval: snapshot.hasPendingApproval,
+            updatedAt: snapshot.updatedAt
+          }
+        });
+      } catch (error) {
+        console.warn('[WARN] Failed to notify session runtime listener:', error.message);
+      }
+    });
+  }));
+}

package/server/session-core/runtimeWriter.js

@@ -0,0 +1,59 @@
+import { normalizeRealtimePayloadToConversationEvents } from '../../shared/conversationEvents.js';
+import { appendMirroredConversationEvents } from './eventStore.js';
+import { publishSessionRuntimeStateChanges } from './runtimeState.js';
+
+export class SessionEventMirrorWriter {
+  constructor(writer, provider = 'claude') {
+    this.writer = writer;
+    this.provider = provider;
+    this.sessionId = null;
+    this.isWebSocketWriter = writer?.isWebSocketWriter;
+    this.isSSEStreamWriter = writer?.isSSEStreamWriter;
+  }
+
+  send(data) {
+    if (data?.sessionId) {
+      this.sessionId = data.sessionId;
+    }
+
+    this.writer.send(data);
+
+    const normalizedEvents = normalizeRealtimePayloadToConversationEvents({
+      ...data,
+      provider: data?.provider || this.provider,
+      sessionId: data?.sessionId || this.sessionId
+    }, this.provider);
+
+    normalizedEvents.forEach((event) => {
+      this.writer.send({
+        type: 'conversation-event',
+        provider: event.provider,
+        sessionId: event.sessionId,
+        event
+      });
+    });
+
+    if (normalizedEvents.length > 0) {
+      void appendMirroredConversationEvents(normalizedEvents).catch((error) => {
+        console.warn('[WARN] Failed to persist mirrored conversation events:', error.message);
+      });
+      void publishSessionRuntimeStateChanges(normalizedEvents).catch((error) => {
+        console.warn('[WARN] Failed to publish runtime state changes:', error.message);
+      });
+    }
+  }
+
+  setSessionId(sessionId) {
+    this.sessionId = sessionId;
+    if (typeof this.writer.setSessionId === 'function') {
+      this.writer.setSessionId(sessionId);
+    }
+  }
+
+  getSessionId() {
+    if (typeof this.writer.getSessionId === 'function') {
+      return this.writer.getSessionId();
+    }
+    return this.sessionId;
+  }
+}

package/server/utils/agentCallback.js

@@ -0,0 +1,273 @@
+import crypto from 'crypto';
+import fetch from 'node-fetch';
+
+export const DEFAULT_AGENT_CALLBACK_EVENTS = ['completed', 'errored', 'aborted'];
+const VALID_AGENT_CALLBACK_EVENTS = new Set(DEFAULT_AGENT_CALLBACK_EVENTS);
+const CALLBACK_ATTEMPT_TIMEOUT_MS = 5000;
+const CALLBACK_RETRY_DELAYS_MS = [0, 1000, 5000];
+
+export function normalizeAgentCallbackConfig(rawCallback) {
+  if (rawCallback == null) {
+    return null;
+  }
+
+  if (!rawCallback || typeof rawCallback !== 'object' || Array.isArray(rawCallback)) {
+    throw new Error('callback must be an object');
+  }
+
+  const rawUrl = typeof rawCallback.url === 'string' ? rawCallback.url.trim() : '';
+  if (!rawUrl) {
+    throw new Error('callback.url is required when callback is provided');
+  }
+
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(rawUrl);
+  } catch {
+    throw new Error('callback.url must be a valid URL');
+  }
+
+  if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
+    throw new Error('callback.url must use http or https');
+  }
+
+  if (rawCallback.secret !== undefined && typeof rawCallback.secret !== 'string') {
+    throw new Error('callback.secret must be a string when provided');
+  }
+
+  const eventsInput = rawCallback.events === undefined
+    ? DEFAULT_AGENT_CALLBACK_EVENTS
+    : rawCallback.events;
+
+  if (!Array.isArray(eventsInput)) {
+    throw new Error('callback.events must be an array when provided');
+  }
+
+  const normalizedEvents = [];
+  for (const event of eventsInput) {
+    if (typeof event !== 'string') {
+      throw new Error('callback.events must only contain strings');
+    }
+
+    const normalizedEvent = event.trim().toLowerCase();
+    if (!VALID_AGENT_CALLBACK_EVENTS.has(normalizedEvent)) {
+      throw new Error('callback.events can only include completed, errored, or aborted');
+    }
+
+    if (!normalizedEvents.includes(normalizedEvent)) {
+      normalizedEvents.push(normalizedEvent);
+    }
+  }
+
+  return {
+    url: parsedUrl.toString(),
+    events: normalizedEvents,
+    secret: rawCallback.secret ? rawCallback.secret : null
+  };
+}
+
+export function shouldDeliverAgentCallback(callbackConfig, event) {
+  return !!(callbackConfig && callbackConfig.events.includes(event));
+}
+
+export function createAgentCallbackEventId() {
+  if (typeof crypto.randomUUID === 'function') {
+    return `agentcb_${crypto.randomUUID()}`;
+  }
+
+  return `agentcb_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function createEmptyTokenSummary() {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheCreationTokens: 0,
+    totalTokens: 0
+  };
+}
+
+function normalizeResult(result = {}) {
+  return {
+    sessionPath: result.sessionPath ?? null,
+    sessionUrl: result.sessionUrl ?? null,
+    messages: Array.isArray(result.messages) ? result.messages : [],
+    tokens: result.tokens && typeof result.tokens === 'object'
+      ? {
+          inputTokens: Number(result.tokens.inputTokens) || 0,
+          outputTokens: Number(result.tokens.outputTokens) || 0,
+          cacheReadTokens: Number(result.tokens.cacheReadTokens) || 0,
+          cacheCreationTokens: Number(result.tokens.cacheCreationTokens) || 0,
+          totalTokens: Number(result.tokens.totalTokens) || 0
+        }
+      : createEmptyTokenSummary(),
+    branch: result.branch ?? null,
+    pullRequest: result.pullRequest ?? null
+  };
+}
+
+export function buildAgentCallbackPayload({
+  event,
+  eventId,
+  sessionId = null,
+  provider,
+  projectPath = null,
+  isResumed = false,
+  startedAt,
+  finishedAt,
+  result,
+  error = null
+}) {
+  const success = event === 'completed';
+
+  return {
+    event,
+    eventId,
+    sessionId,
+    provider,
+    status: event,
+    success,
+    projectPath,
+    isResumed,
+    startedAt,
+    finishedAt,
+    result: normalizeResult(result),
+    error: error ? { message: error.message || String(error) } : null
+  };
+}
+
+export function signAgentCallbackBody(secret, rawBody) {
+  const digest = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
+  return `sha256=${digest}`;
+}
+
+function getCallbackTargetHost(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+export async function deliverAgentCallbackAttempt({
+  callback,
+  payload,
+  eventId,
+  attempt,
+  logger = console
+}) {
+  const rawBody = JSON.stringify(payload);
+  const headers = {
+    'Content-Type': 'application/json',
+    'User-Agent': 'Axhub-Genie-Callback/1.0',
+    'X-Agent-Event': payload.event,
+    'X-Agent-Event-Id': eventId,
+    'X-Agent-Delivery-Attempt': String(attempt),
+  };
+
+  if (callback.secret) {
+    headers['X-Agent-Signature'] = signAgentCallbackBody(callback.secret, rawBody);
+  }
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), CALLBACK_ATTEMPT_TIMEOUT_MS);
+  const host = getCallbackTargetHost(callback.url);
+
+  try {
+    const response = await fetch(callback.url, {
+      method: 'POST',
+      headers,
+      body: rawBody,
+      signal: controller.signal
+    });
+
+    const retryable = response.status >= 500;
+    logger.info?.(
+      `[AgentCallback] attempt=${attempt} eventId=${eventId} sessionId=${payload.sessionId || 'unknown'} host=${host} status=${response.status}`
+    );
+
+    return {
+      ok: response.ok,
+      status: response.status,
+      retryable
+    };
+  } catch (error) {
+    const isAbortTimeout = error?.name === 'AbortError';
+    logger.warn?.(
+      `[AgentCallback] attempt=${attempt} eventId=${eventId} sessionId=${payload.sessionId || 'unknown'} host=${host} error=${isAbortTimeout ? 'timeout' : (error.message || error)}`
+    );
+
+    return {
+      ok: false,
+      status: null,
+      retryable: true,
+      error
+    };
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+export async function deliverAgentCallbackWithRetry({
+  callback,
+  payload,
+  logger = console
+}) {
+  const eventId = payload.eventId;
+  let finalResult = null;
+
+  for (let index = 0; index < CALLBACK_RETRY_DELAYS_MS.length; index += 1) {
+    const attempt = index + 1;
+    const delayMs = CALLBACK_RETRY_DELAYS_MS[index];
+
+    if (delayMs > 0) {
+      await sleep(delayMs);
+    }
+
+    const result = await deliverAgentCallbackAttempt({
+      callback,
+      payload,
+      eventId,
+      attempt,
+      logger
+    });
+    finalResult = result;
+
+    if (result.ok) {
+      return result;
+    }
+
+    if (!result.retryable || attempt >= CALLBACK_RETRY_DELAYS_MS.length) {
+      break;
+    }
+  }
+
+  logger.warn?.(
+    `[AgentCallback] delivery_failed eventId=${eventId} sessionId=${payload.sessionId || 'unknown'} host=${getCallbackTargetHost(callback.url)} status=${finalResult?.status ?? 'n/a'}`
+  );
+
+  return finalResult;
+}
+
+export function scheduleAgentCallbackDelivery({
+  callback,
+  payload,
+  logger = console
+}) {
+  return Promise.resolve().then(() => deliverAgentCallbackWithRetry({
+    callback,
+    payload,
+    logger
+  })).catch((error) => {
+    logger.warn?.(
+      `[AgentCallback] unexpected_delivery_error eventId=${payload?.eventId || 'unknown'} error=${error.message || error}`
+    );
+  });
+}