@valni/cli-darwin-x64 0.0.0-stage → 0.1.2

package/runtime/examples/sdk/README.md

@@ -0,0 +1,140 @@
+# SDK Examples
+
+Programmatic usage of pi-coding-agent via `createAgentSession()` and `createAgentSessionRuntime()`.
+
+The runtime example shows how to build a recreate function that closes over process-global fixed inputs and recreates cwd-bound services and sessions as the active session cwd changes.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| `01-minimal.ts` | Simplest usage with all defaults |
+| `02-custom-model.ts` | Select model and thinking level |
+| `03-custom-prompt.ts` | Replace or modify system prompt |
+| `04-skills.ts` | Discover, filter, or replace skills |
+| `05-tools.ts` | Built-in tool allowlists |
+| `06-extensions.ts` | Logging, blocking, result modification |
+| `07-context-files.ts` | AGENTS.md context files |
+| `08-slash-commands.ts` | File-based slash commands |
+| `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
+| `10-settings.ts` | Override compaction, retry, terminal settings |
+| `11-sessions.ts` | In-memory, persistent, continue, list sessions |
+| `12-full-control.ts` | Replace everything, no discovery |
+| `13-session-runtime.ts` | Manage runtime-backed session replacement |
+
+## Running
+
+```bash
+cd packages/coding-agent
+npx tsx examples/sdk/01-minimal.ts
+```
+
+## Quick Reference
+
+```typescript
+import { getModel } from "@valni/ai";
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  ModelRuntime,
+  SessionManager,
+  SettingsManager,
+} from "@valni/cli";
+
+const modelRuntime = await ModelRuntime.create();
+
+// Minimal
+const { session } = await createAgentSession({ modelRuntime });
+
+// Custom model
+const model = getModel("anthropic", "claude-opus-4-5");
+const { session } = await createAgentSession({ model, thinkingLevel: "high", modelRuntime });
+
+// Modify prompt
+const loader = new DefaultResourceLoader({
+  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
+});
+await loader.reload();
+const { session } = await createAgentSession({ resourceLoader: loader, modelRuntime });
+
+// Read-only
+const { session } = await createAgentSession({ tools: ["read", "grep", "find", "ls"], modelRuntime });
+
+// In-memory
+const { session } = await createAgentSession({
+  sessionManager: SessionManager.inMemory(),
+  modelRuntime,
+});
+
+// Full control
+const customRuntime = await ModelRuntime.create({
+  authPath: "/my/app/auth.json",
+  modelsPath: "/my/app/models.json",
+});
+customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+
+const resourceLoader = new DefaultResourceLoader({
+  systemPromptOverride: () => "You are helpful.",
+  extensionFactories: [myExtension],
+  skillsOverride: () => ({ skills: [], diagnostics: [] }),
+  agentsFilesOverride: () => ({ agentsFiles: [] }),
+  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+});
+await resourceLoader.reload();
+
+const { session } = await createAgentSession({
+  model,
+  modelRuntime: customRuntime,
+  resourceLoader,
+  tools: ["read", "bash", "my_tool"],
+  customTools: [myTool],
+  sessionManager: SessionManager.inMemory(),
+  settingsManager: SettingsManager.inMemory(),
+});
+
+// Run prompts
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+await session.prompt("Hello");
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `modelRuntime` | Runtime using `agentDir/auth.json` and `models.json` | Canonical model and authentication runtime |
+| `cwd` | `process.cwd()` | Working directory |
+| `agentDir` | `~/.valni/agent` | Config directory |
+| `model` | From settings/first available | Model to use |
+| `thinkingLevel` | From settings/"off" | off, low, medium, high |
+| `tools` | `["read", "bash", "edit", "write"]` built-ins | Allowlist tool names across built-in, extension, and custom tools |
+| `customTools` | `[]` | Additional tool definitions |
+| `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes, and context files |
+| `sessionManager` | `SessionManager.create(cwd)` | Persistence |
+| `settingsManager` | `SettingsManager.create(cwd, agentDir)` | Settings overrides |
+
+## Events
+
+```typescript
+session.subscribe((event) => {
+  switch (event.type) {
+    case "message_update":
+      if (event.assistantMessageEvent.type === "text_delta") {
+        process.stdout.write(event.assistantMessageEvent.delta);
+      }
+      break;
+    case "tool_execution_start":
+      console.log(`Tool: ${event.toolName}`);
+      break;
+    case "tool_execution_end":
+      console.log(`Result: ${event.result}`);
+      break;
+    case "agent_end":
+      console.log("Done");
+      break;
+  }
+});
+```

package/runtime/export-html/ansi-to-html.js

@@ -0,0 +1,249 @@
+/**
+ * ANSI escape code to HTML converter.
+ *
+ * Converts terminal ANSI color/style codes to HTML with inline styles.
+ * Supports:
+ * - Standard foreground colors (30-37) and bright variants (90-97)
+ * - Standard background colors (40-47) and bright variants (100-107)
+ * - 256-color palette (38;5;N and 48;5;N)
+ * - RGB true color (38;2;R;G;B and 48;2;R;G;B)
+ * - Text styles: bold (1), dim (2), italic (3), underline (4)
+ * - Reset (0)
+ */
+// Standard ANSI color palette (0-15)
+const ANSI_COLORS = [
+    "#000000", // 0: black
+    "#800000", // 1: red
+    "#008000", // 2: green
+    "#808000", // 3: yellow
+    "#000080", // 4: blue
+    "#800080", // 5: magenta
+    "#008080", // 6: cyan
+    "#c0c0c0", // 7: white
+    "#808080", // 8: bright black
+    "#ff0000", // 9: bright red
+    "#00ff00", // 10: bright green
+    "#ffff00", // 11: bright yellow
+    "#0000ff", // 12: bright blue
+    "#ff00ff", // 13: bright magenta
+    "#00ffff", // 14: bright cyan
+    "#ffffff", // 15: bright white
+];
+/**
+ * Convert 256-color index to hex.
+ */
+function color256ToHex(index) {
+    // Standard colors (0-15)
+    if (index < 16) {
+        return ANSI_COLORS[index];
+    }
+    // Color cube (16-231): 6x6x6 = 216 colors
+    if (index < 232) {
+        const cubeIndex = index - 16;
+        const r = Math.floor(cubeIndex / 36);
+        const g = Math.floor((cubeIndex % 36) / 6);
+        const b = cubeIndex % 6;
+        const toComponent = (n) => (n === 0 ? 0 : 55 + n * 40);
+        const toHex = (n) => toComponent(n).toString(16).padStart(2, "0");
+        return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+    }
+    // Grayscale (232-255): 24 shades
+    const gray = 8 + (index - 232) * 10;
+    const grayHex = gray.toString(16).padStart(2, "0");
+    return `#${grayHex}${grayHex}${grayHex}`;
+}
+/**
+ * Escape HTML special characters.
+ */
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#039;");
+}
+function createEmptyStyle() {
+    return {
+        fg: null,
+        bg: null,
+        bold: false,
+        dim: false,
+        italic: false,
+        underline: false,
+    };
+}
+function styleToInlineCSS(style) {
+    const parts = [];
+    if (style.fg)
+        parts.push(`color:${style.fg}`);
+    if (style.bg)
+        parts.push(`background-color:${style.bg}`);
+    if (style.bold)
+        parts.push("font-weight:bold");
+    if (style.dim)
+        parts.push("opacity:0.6");
+    if (style.italic)
+        parts.push("font-style:italic");
+    if (style.underline)
+        parts.push("text-decoration:underline");
+    return parts.join(";");
+}
+function hasStyle(style) {
+    return style.fg !== null || style.bg !== null || style.bold || style.dim || style.italic || style.underline;
+}
+/**
+ * Parse ANSI SGR (Select Graphic Rendition) codes and update style.
+ */
+function applySgrCode(params, style) {
+    let i = 0;
+    while (i < params.length) {
+        const code = params[i];
+        if (code === 0) {
+            // Reset all
+            style.fg = null;
+            style.bg = null;
+            style.bold = false;
+            style.dim = false;
+            style.italic = false;
+            style.underline = false;
+        }
+        else if (code === 1) {
+            style.bold = true;
+        }
+        else if (code === 2) {
+            style.dim = true;
+        }
+        else if (code === 3) {
+            style.italic = true;
+        }
+        else if (code === 4) {
+            style.underline = true;
+        }
+        else if (code === 22) {
+            // Reset bold/dim
+            style.bold = false;
+            style.dim = false;
+        }
+        else if (code === 23) {
+            style.italic = false;
+        }
+        else if (code === 24) {
+            style.underline = false;
+        }
+        else if (code >= 30 && code <= 37) {
+            // Standard foreground colors
+            style.fg = ANSI_COLORS[code - 30];
+        }
+        else if (code === 38) {
+            // Extended foreground color
+            if (params[i + 1] === 5 && params.length > i + 2) {
+                // 256-color: 38;5;N
+                style.fg = color256ToHex(params[i + 2]);
+                i += 2;
+            }
+            else if (params[i + 1] === 2 && params.length > i + 4) {
+                // RGB: 38;2;R;G;B
+                const r = params[i + 2];
+                const g = params[i + 3];
+                const b = params[i + 4];
+                style.fg = `rgb(${r},${g},${b})`;
+                i += 4;
+            }
+        }
+        else if (code === 39) {
+            // Default foreground
+            style.fg = null;
+        }
+        else if (code >= 40 && code <= 47) {
+            // Standard background colors
+            style.bg = ANSI_COLORS[code - 40];
+        }
+        else if (code === 48) {
+            // Extended background color
+            if (params[i + 1] === 5 && params.length > i + 2) {
+                // 256-color: 48;5;N
+                style.bg = color256ToHex(params[i + 2]);
+                i += 2;
+            }
+            else if (params[i + 1] === 2 && params.length > i + 4) {
+                // RGB: 48;2;R;G;B
+                const r = params[i + 2];
+                const g = params[i + 3];
+                const b = params[i + 4];
+                style.bg = `rgb(${r},${g},${b})`;
+                i += 4;
+            }
+        }
+        else if (code === 49) {
+            // Default background
+            style.bg = null;
+        }
+        else if (code >= 90 && code <= 97) {
+            // Bright foreground colors
+            style.fg = ANSI_COLORS[code - 90 + 8];
+        }
+        else if (code >= 100 && code <= 107) {
+            // Bright background colors
+            style.bg = ANSI_COLORS[code - 100 + 8];
+        }
+        // Ignore unrecognized codes
+        i++;
+    }
+}
+// Match ANSI escape sequences: ESC[ followed by params and ending with 'm'
+const ANSI_REGEX = /\x1b\[([\d;]*)m/g;
+/**
+ * Convert ANSI-escaped text to HTML with inline styles.
+ */
+export function ansiToHtml(text) {
+    const style = createEmptyStyle();
+    let result = "";
+    let lastIndex = 0;
+    let inSpan = false;
+    // Reset regex state
+    ANSI_REGEX.lastIndex = 0;
+    let match = ANSI_REGEX.exec(text);
+    while (match !== null) {
+        // Add text before this escape sequence
+        const beforeText = text.slice(lastIndex, match.index);
+        if (beforeText) {
+            result += escapeHtml(beforeText);
+        }
+        // Parse SGR parameters
+        const paramStr = match[1];
+        const params = paramStr ? paramStr.split(";").map((p) => parseInt(p, 10) || 0) : [0];
+        // Close existing span if we have one
+        if (inSpan) {
+            result += "</span>";
+            inSpan = false;
+        }
+        // Apply the codes
+        applySgrCode(params, style);
+        // Open new span if we have any styling
+        if (hasStyle(style)) {
+            result += `<span style="${styleToInlineCSS(style)}">`;
+            inSpan = true;
+        }
+        lastIndex = match.index + match[0].length;
+        match = ANSI_REGEX.exec(text);
+    }
+    // Add remaining text
+    const remainingText = text.slice(lastIndex);
+    if (remainingText) {
+        result += escapeHtml(remainingText);
+    }
+    // Close any open span
+    if (inSpan) {
+        result += "</span>";
+    }
+    return result;
+}
+/**
+ * Convert array of ANSI-escaped lines to HTML.
+ * Each line is wrapped in a div element.
+ */
+export function ansiLinesToHtml(lines) {
+    return lines.map((line) => `<div class="ansi-line">${ansiToHtml(line) || "&nbsp;"}</div>`).join("");
+}
+//# sourceMappingURL=ansi-to-html.js.map

package/runtime/export-html/index.js

@@ -0,0 +1,226 @@
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { basename, join } from "path";
+import { APP_NAME, getExportTemplateDir } from "../../config.js";
+import { getResolvedThemeColors, getThemeExportColors } from "../../modes/interactive/theme/theme.js";
+import { normalizePath, resolvePath } from "../../utils/paths.js";
+import { SessionManager } from "../session-manager.js";
+/** Parse a color string to RGB values. Supports hex (#RRGGBB) and rgb(r,g,b) formats. */
+function parseColor(color) {
+    const hexMatch = color.match(/^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/);
+    if (hexMatch) {
+        return {
+            r: Number.parseInt(hexMatch[1], 16),
+            g: Number.parseInt(hexMatch[2], 16),
+            b: Number.parseInt(hexMatch[3], 16),
+        };
+    }
+    const rgbMatch = color.match(/^rgb\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/);
+    if (rgbMatch) {
+        return {
+            r: Number.parseInt(rgbMatch[1], 10),
+            g: Number.parseInt(rgbMatch[2], 10),
+            b: Number.parseInt(rgbMatch[3], 10),
+        };
+    }
+    return undefined;
+}
+/** Calculate relative luminance of a color (0-1, higher = lighter). */
+function getLuminance(r, g, b) {
+    const toLinear = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+/** Adjust color brightness. Factor > 1 lightens, < 1 darkens. */
+function adjustBrightness(color, factor) {
+    const parsed = parseColor(color);
+    if (!parsed)
+        return color;
+    const adjust = (c) => Math.min(255, Math.max(0, Math.round(c * factor)));
+    return `rgb(${adjust(parsed.r)}, ${adjust(parsed.g)}, ${adjust(parsed.b)})`;
+}
+/** Derive export background colors from a base color (e.g., userMessageBg). */
+function deriveExportColors(baseColor) {
+    const parsed = parseColor(baseColor);
+    if (!parsed) {
+        return {
+            pageBg: "rgb(24, 24, 30)",
+            cardBg: "rgb(30, 30, 36)",
+            infoBg: "rgb(60, 55, 40)",
+        };
+    }
+    const luminance = getLuminance(parsed.r, parsed.g, parsed.b);
+    const isLight = luminance > 0.5;
+    if (isLight) {
+        return {
+            pageBg: adjustBrightness(baseColor, 0.96),
+            cardBg: baseColor,
+            infoBg: `rgb(${Math.min(255, parsed.r + 10)}, ${Math.min(255, parsed.g + 5)}, ${Math.max(0, parsed.b - 20)})`,
+        };
+    }
+    return {
+        pageBg: adjustBrightness(baseColor, 0.7),
+        cardBg: adjustBrightness(baseColor, 0.85),
+        infoBg: `rgb(${Math.min(255, parsed.r + 20)}, ${Math.min(255, parsed.g + 15)}, ${parsed.b})`,
+    };
+}
+/**
+ * Generate CSS custom property declarations from theme colors.
+ */
+function generateThemeVars(themeName) {
+    const colors = getResolvedThemeColors(themeName);
+    const lines = [];
+    for (const [key, value] of Object.entries(colors)) {
+        lines.push(`--${key}: ${value};`);
+    }
+    // Use explicit theme export colors if available, otherwise derive from userMessageBg
+    const themeExport = getThemeExportColors(themeName);
+    const userMessageBg = colors.userMessageBg || "#343541";
+    const derivedColors = deriveExportColors(userMessageBg);
+    lines.push(`--exportPageBg: ${themeExport.pageBg ?? derivedColors.pageBg};`);
+    lines.push(`--exportCardBg: ${themeExport.cardBg ?? derivedColors.cardBg};`);
+    lines.push(`--exportInfoBg: ${themeExport.infoBg ?? derivedColors.infoBg};`);
+    return lines.join("\n      ");
+}
+/**
+ * Core HTML generation logic shared by both export functions.
+ */
+function generateHtml(sessionData, themeName) {
+    const templateDir = getExportTemplateDir();
+    const template = readFileSync(join(templateDir, "template.html"), "utf-8");
+    const templateCss = readFileSync(join(templateDir, "template.css"), "utf-8");
+    const templateJs = readFileSync(join(templateDir, "template.js"), "utf-8");
+    const markedJs = readFileSync(join(templateDir, "vendor", "marked.min.js"), "utf-8");
+    const hljsJs = readFileSync(join(templateDir, "vendor", "highlight.min.js"), "utf-8");
+    const themeVars = generateThemeVars(themeName);
+    const colors = getResolvedThemeColors(themeName);
+    const themeExport = getThemeExportColors(themeName);
+    const derivedExportColors = deriveExportColors(colors.userMessageBg || "#343541");
+    const bodyBg = themeExport.pageBg ?? derivedExportColors.pageBg;
+    const containerBg = themeExport.cardBg ?? derivedExportColors.cardBg;
+    const infoBg = themeExport.infoBg ?? derivedExportColors.infoBg;
+    // Base64 encode session data to avoid escaping issues
+    const sessionDataBase64 = Buffer.from(JSON.stringify(sessionData)).toString("base64");
+    // Build the CSS with theme variables injected
+    const css = templateCss
+        .replace("{{THEME_VARS}}", themeVars)
+        .replace("{{BODY_BG}}", bodyBg)
+        .replace("{{CONTAINER_BG}}", containerBg)
+        .replace("{{INFO_BG}}", infoBg);
+    return template
+        .replace("{{CSS}}", css)
+        .replace("{{JS}}", templateJs)
+        .replace("{{SESSION_DATA}}", sessionDataBase64)
+        .replace("{{MARKED_JS}}", markedJs)
+        .replace("{{HIGHLIGHT_JS}}", hljsJs);
+}
+/** Tools rendered directly by the HTML template (not pre-rendered via TUI→ANSI→HTML pipeline) */
+const TEMPLATE_RENDERED_TOOLS = new Set(["bash", "read", "write", "edit", "ls"]);
+/**
+ * Pre-render custom tools to HTML using their TUI renderers.
+ */
+function preRenderCustomTools(entries, toolRenderer) {
+    const renderedTools = {};
+    for (const entry of entries) {
+        if (entry.type !== "message")
+            continue;
+        const msg = entry.message;
+        // Find tool calls in assistant messages
+        if (msg.role === "assistant" && Array.isArray(msg.content)) {
+            for (const block of msg.content) {
+                if (block.type === "toolCall" && !TEMPLATE_RENDERED_TOOLS.has(block.name)) {
+                    const callHtml = toolRenderer.renderCall(block.id, block.name, block.arguments);
+                    if (callHtml) {
+                        renderedTools[block.id] = { callHtml };
+                    }
+                }
+            }
+        }
+        // Find tool results
+        if (msg.role === "toolResult" && msg.toolCallId) {
+            const toolName = msg.toolName || "";
+            // Only render if we have a pre-rendered call OR it's not template-rendered
+            const existing = renderedTools[msg.toolCallId];
+            if (existing || !TEMPLATE_RENDERED_TOOLS.has(toolName)) {
+                const rendered = toolRenderer.renderResult(msg.toolCallId, toolName, msg.content, msg.details, msg.isError || false);
+                if (rendered) {
+                    renderedTools[msg.toolCallId] = {
+                        ...existing,
+                        resultHtmlCollapsed: rendered.collapsed,
+                        resultHtmlExpanded: rendered.expanded,
+                    };
+                }
+            }
+        }
+    }
+    return renderedTools;
+}
+/**
+ * Export session to HTML using SessionManager and AgentState.
+ * Used by TUI's /export command.
+ */
+export async function exportSessionToHtml(sm, state, options) {
+    const opts = typeof options === "string" ? { outputPath: options } : options || {};
+    const sessionFile = sm.getSessionFile();
+    if (!sessionFile) {
+        throw new Error("Cannot export in-memory session to HTML");
+    }
+    if (!existsSync(sessionFile)) {
+        throw new Error("Nothing to export yet - start a conversation first");
+    }
+    const entries = sm.getEntries();
+    // Pre-render custom tools if a tool renderer is provided
+    let renderedTools;
+    if (opts.toolRenderer) {
+        renderedTools = preRenderCustomTools(entries, opts.toolRenderer);
+        // Only include if we actually rendered something
+        if (Object.keys(renderedTools).length === 0) {
+            renderedTools = undefined;
+        }
+    }
+    const sessionData = {
+        header: sm.getHeader(),
+        entries,
+        leafId: sm.getLeafId(),
+        systemPrompt: state?.systemPrompt,
+        tools: state?.tools?.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters })),
+        renderedTools,
+    };
+    const html = generateHtml(sessionData, opts.themeName);
+    let outputPath = opts.outputPath ? normalizePath(opts.outputPath) : undefined;
+    if (!outputPath) {
+        const sessionBasename = basename(sessionFile, ".jsonl");
+        outputPath = `${APP_NAME}-session-${sessionBasename}.html`;
+    }
+    writeFileSync(outputPath, html, "utf8");
+    return outputPath;
+}
+/**
+ * Export session file to HTML (standalone, without AgentState).
+ * Used by CLI for exporting arbitrary session files.
+ */
+export async function exportFromFile(inputPath, options) {
+    const opts = typeof options === "string" ? { outputPath: options } : options || {};
+    const resolvedInputPath = resolvePath(inputPath);
+    if (!existsSync(resolvedInputPath)) {
+        throw new Error(`File not found: ${resolvedInputPath}`);
+    }
+    const sm = SessionManager.open(resolvedInputPath);
+    const sessionData = {
+        header: sm.getHeader(),
+        entries: sm.getEntries(),
+        leafId: sm.getLeafId(),
+        systemPrompt: undefined,
+        tools: undefined,
+    };
+    const html = generateHtml(sessionData, opts.themeName);
+    let outputPath = opts.outputPath ? normalizePath(opts.outputPath) : undefined;
+    if (!outputPath) {
+        const inputBasename = basename(resolvedInputPath, ".jsonl");
+        outputPath = `${APP_NAME}-session-${inputBasename}.html`;
+    }
+    writeFileSync(outputPath, html, "utf8");
+    return outputPath;
+}
+//# sourceMappingURL=index.js.map