commentary

2026-09-16 09:31:20 -04:00 · 2026-04-28 20:49:07 -04:00
parent 053dfc6396
commit b0f62e1cad
6 changed files with 886 additions and 808 deletions
@@ -0,0 +1,123 @@
+// llm Commentary Service runtime helpers
+// Purpose: Provides pure helpers for admin state projection, role checks, and structured error normalization.
+// Scope: Keeps runtime behavior unchanged by extracting deterministic helper logic from index orchestration.
+function isAdminRole(role) {
+  return role === 'admin' || role === 'lockdown' || role === 'lockdown-admin';
+}
+
+function buildAdminState(status, runHistory) {
+  return {
+    runtime: {
+      running: status.running,
+      inFlight: status.inFlight,
+      phase: status.phase,
+      phaseAt: status.phaseAt,
+      currentRunId: status.currentRunId,
+      tickCount: status.tickCount,
+      lastTickAt: status.lastTickAt,
+      nextRunAt: status.nextRunAt,
+      outcome: status.lastOutcome,
+      reason: status.lastReason,
+    },
+    counters: {
+      clearCount: status.clearCount,
+      skipStreak: status.skipStreak,
+      promptChars: status.lastPromptChars,
+      snapshotSummary: status.lastSnapshotSummary,
+    },
+    timings: {
+      lastGenerationMs: status.lastGenerationMs,
+      avgGenerationMs: status.avgGenerationMs,
+      generationCount: status.generationCount,
+    },
+    input: {
+      promptPath: status.promptPath,
+      systemPrompt: status.lastSystemPrompt,
+      infoSnapshot: status.lastInfoSnapshot,
+      modelMessages: status.lastModelMessages,
+      modelInputAt: status.lastModelInputAt,
+      modelInputTickId: status.lastModelInputTickId,
+    },
+    output: {
+      raw: status.lastModelRawOutput,
+      generated: status.lastGeneratedText,
+      posted: status.lastPostedText,
+      postedAt: status.lastPostedAt,
+      modelOutputAt: status.lastModelOutputAt,
+      modelOutputTickId: status.lastModelOutputTickId,
+    },
+    errors: {
+      message: status.lastError,
+      details: status.lastErrorDetails,
+      failedAt: status.lastFailedAt,
+    },
+    history: runHistory,
+    debug: {
+      status,
+    },
+    controls: {
+      supportedActions: ['clearHistory'],
+    },
+  };
+}
+
+function buildFailureInfo(err) {
+  const details = {};
+  if (err && typeof err === 'object') {
+    if (err.name) details.name = String(err.name);
+    if (err.code != null) details.code = String(err.code);
+    if (err.errno != null) details.errno = String(err.errno);
+    if (err.type) details.type = String(err.type);
+    if (err.status != null) details.status = Number(err.status);
+    if (err.statusCode != null) details.statusCode = Number(err.statusCode);
+    if (err.status_code != null) details.status_code = Number(err.status_code);
+    if (err.error) details.error = typeof err.error === 'string' ? err.error : JSON.stringify(err.error);
+    if (err.cause) {
+      if (typeof err.cause === 'string') {
+        details.cause = err.cause;
+      } else if (typeof err.cause === 'object') {
+        details.cause = {
+          name: err.cause.name || null,
+          message: err.cause.message || null,
+          code: err.cause.code || null,
+          status: err.cause.status ?? err.cause.statusCode ?? null,
+        };
+      }
+    }
+    if (err.response && typeof err.response === 'object') {
+      const response = {};
+      if (err.response.status != null) response.status = Number(err.response.status);
+      if (err.response.statusText) response.statusText = String(err.response.statusText);
+      if (err.response.url) response.url = String(err.response.url);
+      if (Object.keys(response).length) {
+        details.response = response;
+      }
+    }
+  }
+
+  const message =
+    (err && typeof err === 'object' && typeof err.message === 'string' && err.message.trim()) ||
+    details.error ||
+    String(err || 'Unknown error');
+
+  const reasonParts = [];
+  if (details.name) reasonParts.push(details.name);
+  const code = details.code || details.errno || details.type;
+  if (code) reasonParts.push(String(code));
+  const status =
+    details.status ??
+    details.statusCode ??
+    details.status_code ??
+    details.response?.status ??
+    null;
+  if (status != null) reasonParts.push(`status ${status}`);
+  const reason = reasonParts.length ? reasonParts.join(' | ') : 'exception';
+
+  return { reason, message, details: Object.keys(details).length ? details : null };
+}
+
+module.exports = {
+  isAdminRole,
+  buildAdminState,
+  buildFailureInfo,
+};