@openlines/opl-pi-sht 0.1.14

package/extensions/opl-simplebench/tests.ts

@@ -0,0 +1,39 @@
+export interface ReasoningFixture {
+  name: string;
+  prompt: string;
+  expectedAnswer: string;
+  category: string;
+}
+
+const finalAnswer = "Reason as needed. Put only the exact answer on your final line.";
+
+export const REASONING_TESTS: ReasoningFixture[] = [
+  { name: "snail_wall", prompt: `A snail climbs 3 feet each day and slides 2 feet each night. The wall is 10 feet tall. How many days until it first reaches the top? ${finalAnswer}`, expectedAnswer: "8", category: "logic" },
+  { name: "math_sequence", prompt: `What is the next number: 2, 6, 18, 54, ? ${finalAnswer}`, expectedAnswer: "162", category: "math" },
+  { name: "spatial_directions", prompt: `Face north. Turn 90 degrees clockwise, then 180 degrees counter-clockwise. Which direction are you facing? ${finalAnswer}`, expectedAnswer: "west", category: "spatial" },
+  { name: "commonsense", prompt: `Can a rooster lay an egg? Answer with a yes or a no only. ${finalAnswer}`, expectedAnswer: "no", category: "commonsense" },
+  { name: "code_simplify", prompt: `What is x after: let x = 0; for (let i = 1; i <= 5; i++) x += i; ${finalAnswer}`, expectedAnswer: "15", category: "code" },
+  { name: "bat_and_ball", prompt: `A bat and ball cost 110 cents. The bat costs 100 cents more than the ball. How many cents does the ball cost? Answer with digits only. ${finalAnswer}`, expectedAnswer: "5", category: "counterint" },
+  { name: "scale_weight", prompt: `One weight is 100 grams. Another is four times as heavy. How many grams does the second weigh? Answer with digits only. ${finalAnswer}`, expectedAnswer: "400", category: "counterint" },
+  { name: "syllogism", prompt: `All mammals are warm-blooded. All dogs are mammals. What property do all dogs have? Answer exactly: warm-blooded. ${finalAnswer}`, expectedAnswer: "warm-blooded", category: "logic" },
+  { name: "if_then_chain", prompt: `If it rains, the ground gets wet. If the ground gets wet, grass grows. It is raining. What happens to the grass? Answer exactly: grass grows. ${finalAnswer}`, expectedAnswer: "grass grows", category: "logic" },
+  { name: "cause_effect", prompt: `A tomato plant produces 4 tomatoes each day for 3 days. How many tomatoes does it produce? Answer with digits only. ${finalAnswer}`, expectedAnswer: "12", category: "causal" },
+  { name: "relative_quantities", prompt: `Tom has three times as many apples as Sara. Sara has five apples. How many apples does Tom have? Answer with digits only. ${finalAnswer}`, expectedAnswer: "15", category: "comparative" },
+  { name: "analogy_1", prompt: `Use the explicitly stated relationship “is the capital city of”: Paris is to France as Tokyo is to which country? Answer exactly one word: Japan or China. Reason as needed. Put only the exact answer on your final line. ${finalAnswer}`, expectedAnswer: "japan", category: "analogy" },
+  { name: "analogy_2", prompt: `3 is to 6 as 5 is to what number? ${finalAnswer}`, expectedAnswer: "10", category: "analogy" },
+  { name: "physics_1", prompt: `Which has more mass? Answer exactly: bowling ball or tennis ball. ${finalAnswer}`, expectedAnswer: "bowling ball", category: "commonsense" },
+  { name: "physics_2", prompt: `Compared with before heating, is a metal spoon hotter or colder after it is heated? ${finalAnswer}`, expectedAnswer: "hotter", category: "commonsense" },
+  { name: "objects_1", prompt: `What tool cuts paper? ${finalAnswer}`, expectedAnswer: "scissors", category: "commonsense" },
+  { name: "social_1", prompt: `Someone says please and thank you. Are they polite or rude? Answer polite or rude. ${finalAnswer}`, expectedAnswer: "polite", category: "commonsense" },
+  { name: "animals_1", prompt: `Dolphins live in water, not on land. Answer exactly: water or land. ${finalAnswer}`, expectedAnswer: "water", category: "commonsense" },
+  { name: "gk_1", prompt: `Which planet is known as the Red Planet? ${finalAnswer}`, expectedAnswer: "mars", category: "commonsense" },
+  { name: "gk_2", prompt: `How many days are in a leap year? ${finalAnswer}`, expectedAnswer: "366", category: "commonsense" },
+];
+
+export const MULTISTEP_INSTRUCTION = `Respond with only this JSON object, with no Markdown or explanation:
+{"operation":"status","requestId":"bench-42","ok":true}`;
+
+export const CALC_TOOL_DEFINITION = {
+  type: "function" as const,
+  function: { name: "calculate", description: "Perform a mathematical calculation", parameters: { type: "object", properties: { expression: { type: "string" } }, required: ["expression"] } },
+};

package/extensions/opl-simplebench/types.ts

@@ -0,0 +1,6 @@
+import type { ServerStats } from "./llama-server";
+
+export interface SimplebenchOptions { model?: string; allModels: boolean; writeArtifact: boolean; thinkingMax?: boolean; codingLite?: boolean; testAll?: boolean; researchLive?: boolean; llamaServer?: boolean; llamagputop?: boolean; tag?: string; }
+export interface RequestMetrics { requestCount: number; retryCount: number; wallTimeMs: number; timeToAnswerMs: number; timeToFirstTokenMs: number | null; startedAt: string | null; finishedAt: string | null; inputTokens: number | null; outputTokens: number | null; totalTokens: number | null; outputTokensPerSecond: number | null; toolCalls: Array<{ name: string; arguments?: unknown }>; }
+export interface TestRecord { id: string; kind: "reasoning" | "instructions" | "tools" | "coding" | "research-grounded" | "research-live"; category?: string; prompt: string; response: string | null; expectedAnswer?: string | string[]; extractedAnswer?: string; score: string; passed: boolean; error: string | null; metrics: RequestMetrics; coding?: { publicPassed: boolean; hiddenPassed: boolean; verifiedAfterEdit: boolean; unrelatedFiles: string[]; toolCalls: number; turns: number; efficiency?: "STRONG" | "MODERATE" | "WEAK" | "FAIL"; }; research?: { toolCalls: string[]; files: string[]; }; }
+export interface RunArtifact { schemaVersion: 1; benchmark: { name: "opl-simplebench"; suite?: "baseline" | "coding-lite" | "test-all"; tag?: string; model: string; provider: string; providerKind: string; thinking: { requested: "default" | "max"; effective: "provider-default" | "openai-reasoning-effort" | "pi-bedrock-reasoning"; level: "max" | null; modelMetadataSource: "active-context" | "scoped-model" | null; }; startedAt: string; finishedAt: string; wallTimeMs: number; artifactEnabled: boolean; }; tests: TestRecord[]; summary: Record<string, unknown> & { serverStats?: ServerStats }; }

package/extensions/opl-simplebench/util/config.ts

@@ -0,0 +1,170 @@
+/**
+ * Shared test utilities for simplebench extension.
+ * Extracted from extensions/simplebench.ts to reduce duplication between
+ * Ollama-specific and Provider-specific test variants.
+ *
+ * @module shared/simplebench-utils
+ * @writtenby VTSTech — https://www.vts-tech.org
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+// ============================================================================
+// Configuration Constants
+// ============================================================================
+
+/**
+ * Configuration constants for model testing.
+ * Centralized to make tuning and maintenance easier.
+ *
+ * @property DEFAULT_TIMEOUT_MS - Default timeout for Ollama API calls (~16.7 min)
+ * @property CONNECT_TIMEOUT_S - Connection timeout for fetch (seconds)
+ * @property MAX_RETRIES - Number of retry attempts for transient failures
+ * @property RETRY_DELAY_MS - Delay between retry attempts (milliseconds)
+ * @property MIN_THINKING_LENGTH - Minimum characters to consider thinking tokens valid
+ * @property TOOL_TEST_TIMEOUT_MS - Timeout for tool usage tests
+ * @property TOOL_SUPPORT_TIMEOUT_MS - Timeout for tool support detection
+ * @property TAGS_TIMEOUT_MS - Timeout for /api/tags requests
+ */
+export const CONFIG = {
+  // General API settings - standardized across all providers
+  DEFAULT_TIMEOUT_MS: 300000,        // 5 minutes - reasonable timeout for all providers
+  CONNECT_TIMEOUT_S: 60,             // 60 seconds to establish connection
+  MAX_RETRIES: 2,                    // Two retries for transient failures (standardized)
+  RETRY_DELAY_MS: 15000,              // 15 seconds between retries (standardized)
+
+  // Test-specific settings - standardized across all providers
+  MIN_THINKING_LENGTH: 10,           // Minimum chars to consider thinking tokens valid
+  TOOL_TEST_TIMEOUT_MS: 300000,       // 5 minutes - consistent timeout for tool usage tests
+  TOOL_SUPPORT_TIMEOUT_MS: 300000,   // 5 minutes - consistent timeout for tool support detection
+
+  // Metadata retrieval
+  TAGS_TIMEOUT_MS: 15000,            // 15 seconds for /api/tags
+  MODEL_INFO_TIMEOUT_MS: 30000,      // 30 seconds for model info lookup
+
+  // Provider API settings
+  PROVIDER_TIMEOUT_MS: 300000,        // 5 minutes - consistent with Ollama
+  PROVIDER_TOOL_TIMEOUT_MS: 300000,   // 5 minutes - consistent with Ollama tool tests
+
+  // Context length fetching
+  CONTEXT_BATCH_SIZE: 3,             // Concurrent requests when fetching model context lengths
+
+  // Rate limiting
+  TEST_DELAY_MS: 4000,              // 4 seconds between tests to avoid rate limiting
+} as const;
+
+// ============================================================================
+// User Configuration Overrides
+// ============================================================================
+
+const TEST_CONFIG_DIR = process.env.PI_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+export const TEST_CONFIG_PATH = path.join(TEST_CONFIG_DIR, "configs", "opl-simplebench.json");
+const LEGACY_TEST_CONFIG_PATH = path.join(TEST_CONFIG_DIR, "simplebench-config.json");
+
+/** Shape of the user configuration file. */
+export interface ModelTestUserConfig {
+  defaultTimeoutMs?: number;
+  connectTimeoutS?: number;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  testDelayMs?: number;
+  toolTestTimeoutMs?: number;
+  providerTimeoutMs?: number;
+  providerToolTimeoutMs?: number;
+  contextBatchSize?: number;
+  researchSearchProvider?: "ddgs" | "searxng";
+  researchSearchUrl?: string;
+  researchMaxResults?: number;
+  llamaServerUrl?: string;
+  llamagputopUrl?: string;
+}
+
+/**
+ * Read user configuration from ~/.pi/agent/simplebench-config.json.
+ * Returns an empty object if the file doesn't exist or is invalid.
+ */
+export function readTestConfig(): ModelTestUserConfig {
+  try {
+    const configPath = fs.existsSync(TEST_CONFIG_PATH) ? TEST_CONFIG_PATH : LEGACY_TEST_CONFIG_PATH;
+    if (fs.existsSync(configPath)) return JSON.parse(fs.readFileSync(configPath, "utf-8")) as ModelTestUserConfig;
+  } catch { /* config read/parse failure is non-critical — defaults are used */ }
+  return {};
+}
+
+/**
+ * Get effective test configuration by merging user overrides with defaults.
+ * User values take precedence over CONFIG defaults.
+ */
+export function getEffectiveConfig(): typeof CONFIG {
+  const userConfig = readTestConfig();
+  return {
+    ...CONFIG,
+    DEFAULT_TIMEOUT_MS: (userConfig.defaultTimeoutMs ?? CONFIG.DEFAULT_TIMEOUT_MS) as typeof CONFIG.DEFAULT_TIMEOUT_MS,
+    CONNECT_TIMEOUT_S: (userConfig.connectTimeoutS ?? CONFIG.CONNECT_TIMEOUT_S) as typeof CONFIG.CONNECT_TIMEOUT_S,
+    MAX_RETRIES: (userConfig.maxRetries ?? CONFIG.MAX_RETRIES) as typeof CONFIG.MAX_RETRIES,
+    RETRY_DELAY_MS: (userConfig.retryDelayMs ?? CONFIG.RETRY_DELAY_MS) as typeof CONFIG.RETRY_DELAY_MS,
+    TEST_DELAY_MS: (userConfig.testDelayMs ?? CONFIG.TEST_DELAY_MS) as typeof CONFIG.TEST_DELAY_MS,
+    TOOL_TEST_TIMEOUT_MS: (userConfig.toolTestTimeoutMs ?? CONFIG.TOOL_TEST_TIMEOUT_MS) as typeof CONFIG.TOOL_TEST_TIMEOUT_MS,
+    PROVIDER_TIMEOUT_MS: (userConfig.providerTimeoutMs ?? CONFIG.PROVIDER_TIMEOUT_MS) as typeof CONFIG.PROVIDER_TIMEOUT_MS,
+    PROVIDER_TOOL_TIMEOUT_MS: (userConfig.providerToolTimeoutMs ?? CONFIG.PROVIDER_TOOL_TIMEOUT_MS) as typeof CONFIG.PROVIDER_TOOL_TIMEOUT_MS,
+    CONTEXT_BATCH_SIZE: (userConfig.contextBatchSize ?? CONFIG.CONTEXT_BATCH_SIZE) as typeof CONFIG.CONTEXT_BATCH_SIZE,
+  };
+}
+
+// ============================================================================
+// Weather Tool Definition (shared across all tool tests)
+// ============================================================================
+
+/**
+ * Standard get_weather tool schema used by all tool usage tests.
+ * Previously copy-pasted in 3+ places — now a single shared constant.
+ */
+export const WEATHER_TOOL_DEFINITION = {
+  type: "function" as const,
+  function: {
+    name: "get_weather",
+    description: "Get the current weather for a location",
+    parameters: {
+      type: "object",
+      properties: {
+        location: { type: "string", description: "City name" },
+        unit: { type: "string", enum: ["celsius", "fahrenheit"] },
+      },
+      required: ["location"],
+    },
+  },
+};
+
+// ============================================================================
+// Tool Support Cache (path only — backing file is no longer written)
+// ============================================================================
+
+const TOOL_SUPPORT_CACHE_DIR = path.join(os.homedir(), ".pi", "agent", "cache");
+export const TOOL_SUPPORT_CACHE_PATH = path.join(TOOL_SUPPORT_CACHE_DIR, "tool_support.json");
+
+// ============================================================================
+// ChatFn Abstraction
+// ============================================================================
+
+/**
+ * Abstraction over Ollama and Provider chat APIs.
+ * Callers wrap their specific chat implementation into this shape.
+ */
+export type ChatMessage = { role: string; content: string; tool_calls?: any[]; tool_call_id?: string };
+
+export function buildToolResultMessages(assistantContent: string, calls: any[], results: string[]): ChatMessage[] {
+  const toolCalls = calls.map((call, index) => ({ ...call, id: call.id || `toolcall${index + 1}` }));
+  return [
+    { role: "assistant", content: assistantContent || "", tool_calls: toolCalls },
+    ...toolCalls.map((call, index) => ({ role: "tool", tool_call_id: call.id, content: results[index] || "INVALID_ARGUMENTS" })),
+  ];
+}
+
+export type ChatFn = (
+  model: string,
+  messages: ChatMessage[],
+  options?: Record<string, unknown>,
+) => Promise<{ content: string; toolCalls?: any[]; elapsedMs: number; raw?: any; requestCount?: number; retryCount?: number; startedAt?: string; finishedAt?: string; timeToFirstTokenMs?: number | null }>;
+

package/extensions/opl-simplebench/util/debug.ts

@@ -0,0 +1,32 @@
+/**
+ * Debug logging utility for Pi Coding Agent extensions.
+ *
+ * Only emits output when the PI_EXTENSIONS_DEBUG environment variable is set to "1".
+ * This allows developers to enable verbose diagnostic logging without impacting
+ * production performance or cluttering normal output.
+ *
+ * @module shared/debug
+ */
+
+const DEBUG_ENABLED = process?.env?.PI_EXTENSIONS_DEBUG === "1";
+
+/**
+ * Log a debug message to stderr (via console.debug).
+ *
+ * @param module - Short identifier for the emitting module (e.g., "ollama", "security")
+ * @param message - Human-readable message describing the event
+ * @param args - Additional values to log alongside the message
+ *
+ * @example
+ * ```typescript
+ * import { debugLog } from "../shared/debug";
+ * try { … } catch (err) {
+ *   debugLog("ollama", "failed to read models.json", err);
+ * }
+ * ```
+ */
+export function debugLog(module: string, message: string, ...args: unknown[]): void {
+  if (!DEBUG_ENABLED) return;
+  const timestamp = new Date().toISOString();
+  console.debug(`[pi-ext:${module}] ${timestamp} ${message}`, ...args);
+}

package/extensions/opl-simplebench/util/format.ts

@@ -0,0 +1,402 @@
+/**
+ * Shared formatting utilities for Pi Coding Agent extensions.
+ * Extracted from diag.ts and simplebench.ts to eliminate duplication.
+ *
+ * @module shared/format
+ * @writtenby VTSTech — https://www.vts-tech.org
+ */
+
+// ============================================================================
+// Section & Indicator Helpers
+// ============================================================================
+
+/**
+ * Render a section header with a horizontal rule.
+ *
+ * Creates a visually distinct section header in the format:
+ * `── TITLE ──────────────────────────────────────────────`
+ *
+ * The horizontal rule automatically fills the remaining space
+ * to create a consistent 60-character wide header.
+ *
+ * @param title - The section title to display
+ * @returns A formatted section header string
+ *
+ * @example
+ * ```typescript
+ * section("REASONING TEST");
+ * // Returns: "\n── REASONING TEST ───────────────────────────────────────"
+ * ```
+ */
+export function section(title: string): string {
+  return `\n── ${title} ${"─".repeat(Math.max(1, 60 - title.length - 4))}`;
+}
+
+/**
+ * Format a success message with a checkmark indicator.
+ *
+ * @param msg - The message to format
+ * @returns The formatted message with ✅ prefix
+ *
+ * @example
+ * ```typescript
+ * ok("Tool call successful");
+ * // Returns: "  ✅ Tool call successful"
+ * ```
+ */
+export function ok(msg: string): string { return `  ✅ ${msg}`; }
+
+/**
+ * Format a failure message with an X indicator.
+ *
+ * @param msg - The message to format
+ * @returns The formatted message with ❌ prefix
+ *
+ * @example
+ * ```typescript
+ * fail("Connection timeout");
+ * // Returns: "  ❌ Connection timeout"
+ * ```
+ */
+export function fail(msg: string): string { return `  ❌ ${msg}`; }
+
+/**
+ * Format a warning message with a warning indicator.
+ *
+ * @param msg - The message to format
+ * @returns The formatted message with ⚠️ prefix
+ *
+ * @example
+ * ```typescript
+ * warn("Model may be too slow for production use");
+ * // Returns: "  ⚠️  Model may be too slow for production use"
+ * ```
+ */
+export function warn(msg: string): string { return `  ⚠️  ${msg}`; }
+
+/**
+ * Format an informational message with an info indicator.
+ *
+ * @param msg - The message to format
+ * @returns The formatted message with ℹ️ prefix
+ *
+ * @example
+ * ```typescript
+ * info("Testing reasoning capability...");
+ * // Returns: "  ℹ️  Testing reasoning capability..."
+ * ```
+ */
+export function info(msg: string): string { return `  ℹ️  ${msg}`; }
+
+// ============================================================================
+// Numeric Formatters
+// ============================================================================
+
+/**
+ * Format bytes as a human-readable string with appropriate units.
+ *
+ * Automatically selects the most appropriate unit (B, KB, MB, GB, TB)
+ * and formats the number with one decimal place.
+ *
+ * @param bytes - The number of bytes to format
+ * @returns A human-readable string representation
+ *
+ * @example
+ * ```typescript
+ * bytesHuman(512);           // "512.0B"
+ * bytesHuman(1536);          // "1.5KB"
+ * bytesHuman(1048576);       // "1.0MB"
+ * bytesHuman(1073741824);    // "1.0GB"
+ * ```
+ */
+export function bytesHuman(bytes: number): string {
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let i = 0;
+  let b = bytes;
+  while (b >= 1024 && i < units.length - 1) { b /= 1024; i++; }
+  return `${b.toFixed(1)}${units[i]}`;
+}
+
+/**
+ * Format milliseconds as a human-readable duration string.
+ *
+ * Automatically selects the most appropriate unit (ms, s, m)
+ * based on the magnitude of the input.
+ *
+ * @param ms - The duration in milliseconds
+ * @returns A human-readable string representation
+ *
+ * @example
+ * ```typescript
+ * msHuman(500);      // "500ms"
+ * msHuman(1500);     // "1.5s"
+ * msHuman(90000);    // "1.5m"
+ * ```
+ */
+export function msHuman(ms: number): string {
+  if (ms < 1000) return `${ms.toFixed(0)}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60000).toFixed(1)}m`;
+}
+
+/**
+ * Format bytes as a compact string for status bar display.
+ *
+ * Uses single-letter suffixes (K, M, G) without spaces,
+ * optimized for narrow display contexts like status bars.
+ *
+ * @param b - The number of bytes to format
+ * @returns A compact string representation
+ *
+ * @example
+ * ```typescript
+ * fmtBytes(512);           // "512K"
+ * fmtBytes(1048576);       // "1.0M"
+ * fmtBytes(1073741824);    // "1.0G"
+ * ```
+ */
+export function fmtBytes(b: number): string {
+  if (b === 0) return "0B";
+  if (b < 1024) return `${b}B`;
+  if (b >= 1073741824) return `${(b / 1073741824).toFixed(1)}G`;
+  if (b >= 1048576) return `${(b / 1048576).toFixed(0)}M`;
+  return `${(b / 1024).toFixed(0)}K`;
+}
+
+/**
+ * Format milliseconds as a compact duration for status bar display.
+ *
+ * For durations over a minute, displays as `Xm Ys` format.
+ * For shorter durations, displays as seconds with one decimal.
+ *
+ * @param ms - The duration in milliseconds
+ * @returns A compact string representation
+ *
+ * @example
+ * ```typescript
+ * fmtDur(500);      // "500ms"
+ * fmtDur(1500);     // "1.5s"
+ * fmtDur(90000);    // "1m30s"
+ * ```
+ */
+export function fmtDur(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60000)}m${Math.round((ms % 60000) / 1000)}s`;
+}
+
+/**
+ * Calculate and format a percentage.
+ *
+ * @param used - The used/occupied amount
+ * @param total - The total capacity
+ * @returns A percentage string with one decimal place
+ *
+ * @example
+ * ```typescript
+ * pct(512, 1024);    // "50.0%"
+ * pct(75, 100);      // "75.0%"
+ * ```
+ */
+export function pct(used: number, total: number): string {
+  if (total === 0) return "0.0%";
+  return `${((used / total) * 100).toFixed(1)}%`;
+}
+
+// ============================================================================
+// String Utilities
+// ============================================================================
+
+/**
+ * Truncate a string to a maximum length with an ellipsis suffix.
+ *
+ * If the string exceeds the maximum length, it is truncated
+ * and "..." is appended to indicate truncation.
+ *
+ * @param s - The string to truncate
+ * @param max - Maximum length before truncation
+ * @returns The original string or truncated version
+ *
+ * @example
+ * ```typescript
+ * truncate("Hello, World!", 5);    // "He..."
+ * truncate("Short", 10);           // "Short"
+ * ```
+ */
+export function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max) + "..." : s;
+}
+
+/**
+ * Strip markdown code fences and truncate large content for clean report output.
+ *
+ * Performs the following transformations:
+ * 1. Removes markdown code fence markers (``` and ```lang)
+ * 2. Collapses excessive blank lines
+ * 3. Detects and truncates HTML content (error pages)
+ * 4. Caps output at a maximum number of lines
+ *
+ * @param s - The string to sanitize
+ * @param maxLines - Maximum number of lines to output (default: 40)
+ * @returns The sanitized and potentially truncated string
+ *
+ * @example
+ * ```typescript
+ * sanitizeForReport("```json\n{\"key\": \"value\"}\n```");
+ * // Returns: "{\"key\": \"value\"}"
+ *
+ * sanitizeForReport(largeHtmlContent);
+ * // Returns: "<!DOCTYPE html>...\n  ℹ️  (HTML response truncated)"
+ * ```
+ */
+export function sanitizeForReport(s: string, maxLines = 40): string {
+  let cleaned = s.replace(/^\s*```[a-zA-Z]*[ \t]*\n?/gm, "");
+  cleaned = cleaned.replace(/^\s*```[ \t]*\n?/gm, "");
+  cleaned = cleaned.replace(/\n{3,}/g, "\n\n").trim();
+
+  // Detect HTML content (error pages, curl failures) and truncate to first few lines
+  // Use strict detection: require a closing tag AND a common HTML opening tag to avoid
+  // false positives on code that mentions HTML-like syntax (e.g., "use <Item> from 'react'")
+  if (/<!DOCTYPE\b|<html[\s>]/i.test(cleaned) || (/<[a-z][\s\S]*>/i.test(cleaned) && cleaned.includes("</") && /<(?:div|span|p|head|body|html|table|form|script)\b/i.test(cleaned))) {
+    const firstLine = cleaned.split("\n")[0];
+    return truncate(firstLine, 200) + "\n  ℹ️  (HTML response truncated)";
+  }
+
+  // Cap line count for any large output
+  const lines = cleaned.split("\n");
+  if (lines.length > maxLines) {
+    cleaned = lines.slice(0, maxLines).join("\n") + `\n  ℹ️  (truncated, ${lines.length - maxLines} more lines)`;
+  }
+
+  return cleaned;
+}
+
+/**
+ * Right-pad a string to a specified length with spaces.
+ *
+ * If the string is already longer than the target length,
+ * it is returned unchanged.
+ *
+ * @param s - The string to pad
+ * @param n - The target length
+ * @returns The padded string
+ *
+ * @example
+ * ```typescript
+ * padRight("test", 10);     // "test      "
+ * padRight("toolong", 5);   // "toolong"
+ * ```
+ */
+export function padRight(s: string, n: number): string {
+  return s + " ".repeat(Math.max(0, n - s.length));
+}
+
+// ============================================================================
+// Model Estimation
+// ============================================================================
+
+/**
+ * Estimate memory usage (in bytes) from parameter size and quantization level.
+ *
+ * Uses bits-per-parameter based on the quantization format:
+ * - FP32/BF16/F16: 16 bits (full precision)
+ * - Q8_0: 8 bits
+ * - Q5_K_M/Q5_M/Q5_K_S/Q5_0/Q5_1: 5.5 bits (average)
+ * - Q4_K_M/Q4_K_S/Q4_0/Q4_1/Q4_M: 4.5 bits (average)
+ * - Q3_K_M/Q3_K_S/Q3_K_L: 3.5 bits (average)
+ * - Q2_K: 2.5 bits (average)
+ * - IQ variants (IQ3_XS, IQ4_XS, etc.): mapped to nearest Q equivalent
+ * - Fallback: 5 bits
+ *
+ * Returns both GPU (VRAM) and CPU (RAM) estimates:
+ * - GPU: base size + 10% overhead (KV cache, runtime allocs — weights dominate)
+ * - CPU: context-aware overhead — KV cache is pre-allocated at model load
+ *   and scales linearly with context window. Formula calibrated against
+ *   real-world Colab CPU observations:
+ *     1.5 + (contextLength / 100_000)
+ *   Without context, falls back to 2.5× (typical mid-range CPU deployment).
+ *
+ * @param parameterSize - Human-readable parameter count (e.g., "7B", "1.5B", "350M")
+ * @param quantizationLevel - Quantization format string (e.g., "Q4_K_M", "BF16")
+ * @param contextLength - Model context window in tokens (e.g., 32768, 131072)
+ * @returns Object with GPU and CPU estimates in bytes, or undefined if unparseable
+ *
+ * @example
+ * ```typescript
+ * estimateMemory("7B", "Q4_K_M", 32768);  // { gpu: ~3.5GB, cpu: ~5.6GB }
+ * estimateMemory("7B", "Q4_K_M", 131072); // { gpu: ~3.5GB, cpu: ~15.8GB }
+ * estimateMemory("350M", "BF16", 32768);   // { gpu: ~0.7GB, cpu: ~1.1GB }
+ * ```
+ */
+export function estimateMemory(parameterSize: string, quantizationLevel: string, contextLength?: number): { gpu: number; cpu: number } | undefined {
+  const params = parseParamCount(parameterSize);
+  if (params === undefined) return undefined;
+
+  const bitsPerParam = bitsPerParamForQuant(quantizationLevel);
+  // Base model size in bytes
+  const modelBytes = (params * bitsPerParam) / 8;
+
+  // CPU overhead scales with context window — KV cache is pre-allocated at load
+  // Calibrated: nemotron 4B Q4, 131k ctx → 2.8× observed (formula gives 2.82×)
+  const cpuMultiplier = contextLength != null
+    ? 1.5 + (contextLength / 100_000)
+    : 2.5; // flat fallback when context unknown
+
+  return {
+    gpu: Math.ceil(modelBytes * 1.1),       // 10% overhead — GPU: weights dominate
+    cpu: Math.ceil(modelBytes * cpuMultiplier), // context-aware — CPU: KV cache dominates
+  };
+}
+
+/**
+ * Parse a human-readable parameter count string to a numeric value.
+ *
+ * Handles formats like "7B", "1.5B", "350M", "13a" (Apple-style),
+ * "70B", "0.6B", "494.03M", etc.
+ *
+ * @param s - The parameter size string
+ * @returns Parameter count as a number, or undefined if unparseable
+ */
+function parseParamCount(s: string): number | undefined {
+  if (!s || typeof s !== "string") return undefined;
+  const str = s.trim().toLowerCase();
+
+  // Match: number + suffix (B/b, M/m, T/t, a/apple)
+  const match = str.match(/^([\d.]+)\s*([bmt]?|a(?:pple)?)$/);
+  if (!match) return undefined;
+
+  const num = parseFloat(match[1]);
+  if (isNaN(num) || num <= 0) return undefined;
+
+  const suffix = match[2];
+  switch (suffix) {
+    case "b": return num * 1e9;
+    case "m": return num * 1e6;
+    case "t": return num * 1e12;
+    case "a": return num * 1e9; // Apple-style (e.g., "3a" = 3B parameters)
+    case "": return num * 1e9; // Bare number assumed to be billions
+    default: return undefined;
+  }
+}
+
+/**
+ * Determine bits per parameter based on quantization format string.
+ */
+function bitsPerParamForQuant(quant: string): number {
+  const q = quant.toUpperCase().replace(/[-_.]/g, "");
+
+  if (q.startsWith("FP32") || q === "F32" || q === "TF32") return 32;
+  if (q.startsWith("F16") || q === "BF16") return 16;
+  if (q.startsWith("Q8")) return 8;
+  if (q.startsWith("IQ4")) return 4.5;
+  if (q.startsWith("IQ3")) return 3.5;
+  if (q.startsWith("IQ2")) return 2.5;
+  if (q.startsWith("IQ1")) return 1.75;
+  if (q.startsWith("Q5") || q.startsWith("Q6")) return 5.5;
+  if (q.startsWith("Q4")) return 4.5;
+  if (q.startsWith("Q3")) return 3.5;
+  if (q.startsWith("Q2")) return 2.5;
+  if (q.startsWith("Q1")) return 1.75;
+
+  return 5; // conservative fallback
+}