@build-astron-co/nimbus 0.2.0 → 0.4.0

package/bin/nimbus

@@ -2,28 +2,44 @@
 # Nimbus CLI launcher — prefers Bun, falls back to Node.js (>=18).
 set -e
 
+# Resolve the real script location, following symlinks so this works when npm
+# installs the bin entry as a symlink (e.g. /opt/homebrew/bin/nimbus ->
+# .../node_modules/@build-astron-co/nimbus/bin/nimbus).
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-ENTRY="$SCRIPT_DIR/../src/nimbus.ts"
+REAL_SCRIPT="$SCRIPT_DIR/nimbus"
+if [ -L "$REAL_SCRIPT" ]; then
+  LINK_TARGET="$(readlink "$REAL_SCRIPT")"
+  case "$LINK_TARGET" in
+    /*) REAL_SCRIPT="$LINK_TARGET" ;;
+    *)  REAL_SCRIPT="$SCRIPT_DIR/$LINK_TARGET" ;;
+  esac
+fi
+PKG_ROOT="$(cd "$(dirname "$REAL_SCRIPT")/.." && pwd)"
+ENTRY="$PKG_ROOT/src/nimbus.ts"
 
 # Prefer Bun for best performance (native bun:sqlite, fast startup)
 if command -v bun >/dev/null 2>&1; then
   exec bun "$ENTRY" "$@"
 fi
 
-# Fallback: Node.js with tsx for TypeScript execution
+# Fallback: Node.js with tsx for TypeScript execution.
+# We use `node --loader tsx/esm` rather than `tsx` directly to ensure ESM
+# output mode — required because yoga-layout (Ink dep) uses top-level await
+# which is incompatible with tsx's default CJS output.
 if command -v node >/dev/null 2>&1; then
   NODE_VERSION=$(node -e "console.log(process.versions.node.split('.')[0])")
   if [ "$NODE_VERSION" -ge 18 ] 2>/dev/null; then
-    # Use tsx (TypeScript eXecute) for Node.js — handles TS natively
-    TSX_BIN="$SCRIPT_DIR/../node_modules/.bin/tsx"
-    if [ -x "$TSX_BIN" ]; then
-      exec "$TSX_BIN" "$ENTRY" "$@"
+    # Prefer the tsx ESM loader bundled with this package
+    TSX_ESM="$PKG_ROOT/node_modules/tsx/dist/esm/index.mjs"
+    if [ -f "$TSX_ESM" ]; then
+      exec node --loader "$TSX_ESM" "$ENTRY" "$@"
     fi
-    # Try global tsx
-    if command -v tsx >/dev/null 2>&1; then
-      exec tsx "$ENTRY" "$@"
+    # Try global tsx ESM loader (npm global install)
+    TSX_GLOBAL_ESM="$(npm root -g 2>/dev/null)/tsx/dist/esm/index.mjs"
+    if [ -f "$TSX_GLOBAL_ESM" ]; then
+      exec node --loader "$TSX_GLOBAL_ESM" "$ENTRY" "$@"
     fi
-    # Last resort: use Node.js --import tsx (Node >= 18.19)
+    # Last resort: node --import tsx (Node >= 18.19, tsx must be globally installed)
     exec node --import tsx "$ENTRY" "$@"
   fi
 fi

package/bin/nimbus.cmd

@@ -0,0 +1,41 @@
+@echo off
+:: Nimbus CLI launcher for Windows (CMD / PowerShell).
+:: Resolves the package root relative to this script's location so it works
+:: when npm installs the bin entry as a junction/shim in node_modules/.bin/.
+
+setlocal enabledelayedexpansion
+
+:: Locate the package root (one level up from this bin\ directory)
+set "SCRIPT_DIR=%~dp0"
+:: Remove trailing backslash
+if "%SCRIPT_DIR:~-1%"=="\" set "SCRIPT_DIR=%SCRIPT_DIR:~0,-1%"
+set "PKG_ROOT=%SCRIPT_DIR%\.."
+set "ENTRY=%PKG_ROOT%\src\nimbus.ts"
+
+:: Primary: Node.js >= 18 with tsx ESM loader (project is Node.js-native)
+where node >nul 2>&1
+if %errorlevel% equ 0 (
+  set "TSX_ESM=%PKG_ROOT%\node_modules\tsx\dist\esm\index.mjs"
+  if exist "!TSX_ESM!" (
+    node --loader "!TSX_ESM!" "%ENTRY%" %*
+    exit /b %errorlevel%
+  )
+  :: Try global tsx loader
+  for /f "delims=" %%i in ('npm root -g 2^>nul') do set "NPM_GLOBAL=%%i"
+  if defined NPM_GLOBAL (
+    set "TSX_GLOBAL=!NPM_GLOBAL!\tsx\dist\esm\index.mjs"
+    if exist "!TSX_GLOBAL!" (
+      node --loader "!TSX_GLOBAL!" "%ENTRY%" %*
+      exit /b %errorlevel%
+    )
+  )
+  :: Last resort: node --import tsx
+  node --import tsx "%ENTRY%" %*
+  exit /b %errorlevel%
+)
+
+echo Error: Nimbus requires Node.js ^>= 18. >&2
+echo. >&2
+echo Install Node.js: >&2
+echo   https://nodejs.org/ >&2
+exit /b 1

package/bin/nimbus.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Nimbus CLI — cross-platform ESM launcher.
+ *
+ * This is the `bin` entry used by npm on all platforms (including Windows).
+ * It locates the package root (following symlinks so npm global installs work),
+ * then spawns Node.js with the tsx ESM loader to execute the TypeScript source.
+ *
+ * Why .mjs instead of a shell script?
+ *   On Windows, npm's cmd-shim cannot wrap a POSIX sh script. A Node.js ESM
+ *   bin entry (#!/usr/bin/env node + .mjs) works on all platforms.
+ */
+
+import { spawnSync, execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+
+// L1: Enable ANSI color support on Windows terminals (Windows 10+ supports VT100).
+// FORCE_COLOR=1 is the standard signal for chalk/ink/supports-color to emit ANSI codes.
+// This must run before any child process is spawned so the env var is inherited.
+if (process.platform === 'win32') {
+  process.env.FORCE_COLOR ??= '1';
+}
+
+// Resolve the true package root, following symlinks (npm global installs symlink on POSIX).
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PKG_ROOT = resolve(__dirname, '..');
+const ENTRY = join(PKG_ROOT, 'src', 'nimbus.ts');
+
+const passArgs = process.argv.slice(2);
+
+function run(nodeArgs) {
+  const result = spawnSync(process.execPath, [...nodeArgs, ENTRY, ...passArgs], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  process.exit(result.status ?? (result.error ? 1 : 0));
+}
+
+// 0. Pre-compiled dist (fastest — no tsx overhead)
+const DIST_ENTRY = join(PKG_ROOT, 'dist', 'src', 'nimbus.js');
+if (existsSync(DIST_ENTRY)) {
+  const result = spawnSync(process.execPath, [DIST_ENTRY, ...passArgs], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  process.exit(result.status ?? (result.error ? 1 : 0));
+}
+
+// 1. tsx ESM loader bundled with this package (most reliable)
+const TSX_BUNDLED = join(PKG_ROOT, 'node_modules', 'tsx', 'dist', 'esm', 'index.mjs');
+if (existsSync(TSX_BUNDLED)) {
+  run(['--loader', TSX_BUNDLED]);
+}
+
+// 2. tsx ESM loader from global npm
+try {
+  const globalRoot = execSync('npm root -g', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  const TSX_GLOBAL = join(globalRoot, 'tsx', 'dist', 'esm', 'index.mjs');
+  if (existsSync(TSX_GLOBAL)) {
+    run(['--loader', TSX_GLOBAL]);
+  }
+} catch {
+  // npm root -g failed — continue
+}
+
+// 3. Last resort: node --import tsx (Node >= 18.19, tsx must be available)
+run(['--import', 'tsx']);

package/completions/nimbus.bash

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+# Dynamic completion helpers
+_nimbus_kubectl_contexts() {
+  kubectl config get-contexts -o name 2>/dev/null
+}
+_nimbus_namespaces() {
+  kubectl get namespaces -o name 2>/dev/null | sed 's|namespace/||'
+}
+_nimbus_tf_workspaces() {
+  terraform workspace list 2>/dev/null | sed 's/^[* ]*//'
+}
+
+_nimbus_completions() {
+  local cur="${COMP_WORDS[COMP_CWORD]}"
+  local prev="${COMP_WORDS[COMP_CWORD-1]}"
+  local commands="chat run plan build deploy init login logout help version upgrade update doctor logs status alias pipeline rollback incident runbook schedule export"
+  # G20: Subcommand completions for terraform/kubectl/helm
+  case "${COMP_WORDS[1]}" in
+    tf|terraform) COMPREPLY=($(compgen -W "init plan apply destroy validate workspace output" -- "${cur}")); return ;;
+    k8s|kubectl)  COMPREPLY=($(compgen -W "get apply delete logs scale rollout exec describe diff" -- "${cur}")); return ;;
+    helm)         COMPREPLY=($(compgen -W "install upgrade rollback uninstall list show diff" -- "${cur}")); return ;;
+    runbook)      COMPREPLY=($(compgen -W "list run create" -- "${cur}")); return ;;
+    schedule)     COMPREPLY=($(compgen -W "list add remove run-now" -- "${cur}")); return ;;
+    export)       COMPREPLY=($(compgen -W "--format --output" -- "${cur}")); return ;;
+  esac
+  case "$prev" in
+    --mode) COMPREPLY=($(compgen -W "plan build deploy" -- "$cur")); return ;;
+    --format) COMPREPLY=($(compgen -W "text json table md html" -- "$cur")); return ;;
+    --ui) COMPREPLY=($(compgen -W "ink readline" -- "$cur")); return ;;
+    --context) COMPREPLY=($(compgen -W "$(_nimbus_kubectl_contexts)" -- "$cur")); return ;;
+    --namespace|-n) COMPREPLY=($(compgen -W "$(_nimbus_namespaces)" -- "$cur")); return ;;
+    --workspace) COMPREPLY=($(compgen -W "$(_nimbus_tf_workspaces)" -- "$cur")); return ;;
+    nimbus) COMPREPLY=($(compgen -W "$commands" -- "$cur")); return ;;
+  esac
+  COMPREPLY=($(compgen -W "--mode --format --auto-approve --stdin --model --max-turns --help --version --context --namespace --workspace --quiet --budget" -- "$cur"))
+}
+complete -F _nimbus_completions nimbus

package/completions/nimbus.fish

@@ -0,0 +1,48 @@
+complete -c nimbus -f
+
+# Subcommands
+complete -c nimbus -n '__fish_use_subcommand' -a chat -d 'Interactive DevOps agent TUI'
+complete -c nimbus -n '__fish_use_subcommand' -a run -d 'Run agent non-interactively'
+complete -c nimbus -n '__fish_use_subcommand' -a plan -d 'Preview infrastructure changes'
+complete -c nimbus -n '__fish_use_subcommand' -a init -d 'Generate NIMBUS.md'
+complete -c nimbus -n '__fish_use_subcommand' -a login -d 'Configure LLM provider'
+complete -c nimbus -n '__fish_use_subcommand' -a logout -d 'Remove credentials'
+complete -c nimbus -n '__fish_use_subcommand' -a help -d 'Show help'
+complete -c nimbus -n '__fish_use_subcommand' -a version -d 'Show version'
+complete -c nimbus -n '__fish_use_subcommand' -a upgrade -d 'Upgrade to latest version'
+complete -c nimbus -n '__fish_use_subcommand' -a update -d 'Alias for upgrade'
+complete -c nimbus -n '__fish_use_subcommand' -a doctor -d 'Check environment'
+complete -c nimbus -n '__fish_use_subcommand' -a logs -d 'Stream Kubernetes pod logs'
+complete -c nimbus -n '__fish_use_subcommand' -a status -d 'Show current agent status'
+complete -c nimbus -n '__fish_use_subcommand' -a alias -d 'Manage command aliases'
+complete -c nimbus -n '__fish_use_subcommand' -a pipeline -d 'Run CI/CD pipeline'
+complete -c nimbus -n '__fish_use_subcommand' -a rollback -d 'Rollback infrastructure changes'
+complete -c nimbus -n '__fish_use_subcommand' -a incident -d 'Incident response session'
+complete -c nimbus -n '__fish_use_subcommand' -a runbook -d 'Execute operational runbooks'
+complete -c nimbus -n '__fish_use_subcommand' -a schedule -d 'Manage periodic automation'
+complete -c nimbus -n '__fish_use_subcommand' -a export -d 'Export session to file'
+
+# G20: Subcommand completions for tf/kubectl/helm
+complete -c nimbus -n '__fish_seen_subcommand_from tf terraform' -a 'init plan apply destroy validate workspace output' -d 'terraform subcommand'
+complete -c nimbus -n '__fish_seen_subcommand_from k8s kubectl' -a 'get apply delete logs scale rollout exec describe diff' -d 'kubectl subcommand'
+complete -c nimbus -n '__fish_seen_subcommand_from helm' -a 'install upgrade rollback uninstall list show diff' -d 'helm subcommand'
+complete -c nimbus -n '__fish_seen_subcommand_from runbook' -a 'list run create' -d 'runbook subcommand'
+complete -c nimbus -n '__fish_seen_subcommand_from schedule' -a 'list add remove run-now' -d 'schedule subcommand'
+
+# Flags
+complete -c nimbus -l mode -a 'plan build deploy' -d 'Agent mode'
+complete -c nimbus -l format -a 'text json table md html' -d 'Output format'
+complete -c nimbus -l auto-approve -d 'Auto-approve permissions'
+complete -c nimbus -l model -d 'LLM model override'
+complete -c nimbus -l max-turns -d 'Maximum agent turns'
+complete -c nimbus -l budget -d 'Cost budget in USD'
+complete -c nimbus -l quiet -s q -d 'Suppress banners and decorative headers'
+
+# Dynamic completions for --context (kubectl contexts)
+complete -c nimbus -l context -d 'kubectl context' -a '(kubectl config get-contexts -o name 2>/dev/null)'
+
+# Dynamic completions for --namespace (kubernetes namespaces)
+complete -c nimbus -l namespace -s n -d 'Kubernetes namespace' -a '(kubectl get namespaces -o name 2>/dev/null | string replace "namespace/" "")'
+
+# Dynamic completions for --workspace (terraform workspaces)
+complete -c nimbus -l workspace -d 'Terraform workspace' -a '(terraform workspace list 2>/dev/null | string replace -r "^[* ]*" "")'

package/completions/nimbus.zsh

@@ -0,0 +1,81 @@
+#compdef nimbus
+
+# Dynamic completion helpers
+_nimbus_kubectl_contexts() {
+  local contexts
+  contexts=(${(f)"$(kubectl config get-contexts -o name 2>/dev/null)"})
+  _describe 'kubectl contexts' contexts
+}
+
+_nimbus_namespaces() {
+  local namespaces
+  namespaces=(${(f)"$(kubectl get namespaces -o name 2>/dev/null | sed 's|namespace/||')"})
+  _describe 'kubernetes namespaces' namespaces
+}
+
+_nimbus_tf_workspaces() {
+  local workspaces
+  workspaces=(${(f)"$(terraform workspace list 2>/dev/null | sed 's/^[* ]*//')"})
+  _describe 'terraform workspaces' workspaces
+}
+
+_nimbus() {
+  local -a commands
+  commands=(
+    'chat:Interactive DevOps agent TUI'
+    'run:Run agent non-interactively'
+    'plan:Preview infrastructure changes'
+    'init:Generate NIMBUS.md project context'
+    'login:Configure LLM provider'
+    'logout:Remove credentials'
+    'help:Show help'
+    'version:Show version'
+    'upgrade:Upgrade to latest version'
+    'update:Alias for upgrade'
+    'doctor:Check environment'
+    'logs:Stream Kubernetes pod logs'
+    'status:Show current agent status'
+    'alias:Manage command aliases'
+    'pipeline:Run CI/CD pipeline'
+    'rollback:Rollback infrastructure changes'
+    'incident:Incident response session'
+    'runbook:Execute operational runbooks'
+    'schedule:Manage periodic automation'
+    'export:Export session to file'
+  )
+  _arguments \
+    '1: :->command' \
+    '--mode[Agent mode]:mode:(plan build deploy)' \
+    '--format[Output format]:format:(text json table md html)' \
+    '--auto-approve[Auto-approve permissions]' \
+    '--model[LLM model]:model:' \
+    '--context[kubectl context]:context:_nimbus_kubectl_contexts' \
+    '--namespace[Kubernetes namespace]:namespace:_nimbus_namespaces' \
+    '--workspace[Terraform workspace]:workspace:_nimbus_tf_workspaces' \
+    '--budget[Cost budget in USD]:budget:' \
+    '--quiet[Suppress banners/headers]' \
+    '--version[Show version]' \
+    '--help[Show help]'
+  # G20: Subcommand completions
+  case ${words[2]} in
+    tf|terraform)
+      local -a tf_cmds; tf_cmds=('init' 'plan' 'apply' 'destroy' 'validate' 'workspace' 'output')
+      _describe 'terraform subcommands' tf_cmds; return ;;
+    k8s|kubectl)
+      local -a k8s_cmds; k8s_cmds=('get' 'apply' 'delete' 'logs' 'scale' 'rollout' 'exec' 'describe' 'diff')
+      _describe 'kubectl subcommands' k8s_cmds; return ;;
+    helm)
+      local -a helm_cmds; helm_cmds=('install' 'upgrade' 'rollback' 'uninstall' 'list' 'show' 'diff')
+      _describe 'helm subcommands' helm_cmds; return ;;
+    runbook)
+      local -a rb_cmds; rb_cmds=('list' 'run' 'create')
+      _describe 'runbook subcommands' rb_cmds; return ;;
+    schedule)
+      local -a sched_cmds; sched_cmds=('list' 'add' 'remove' 'run-now')
+      _describe 'schedule subcommands' sched_cmds; return ;;
+  esac
+  case $state in
+    command) _describe 'nimbus commands' commands ;;
+  esac
+}
+_nimbus "$@"

package/dist/src/agent/compaction-agent.js

@@ -0,0 +1,215 @@
+/**
+ * Compaction Agent
+ *
+ * Uses a fast LLM model (haiku) to summarize earlier conversation context
+ * while preserving key information needed for continuity.
+ *
+ * The compaction agent is invoked automatically by the context manager
+ * when the conversation exceeds the configured threshold, or manually
+ * by the user via a `/compact` command in the TUI.
+ *
+ * Key design decisions:
+ * - Uses the cheapest available model (haiku alias) to minimize cost.
+ * - Truncates very long tool outputs before sending to the summarizer.
+ * - Falls back to a simple extractive summary if the LLM call fails.
+ * - Preserves all technical details, file paths, and decisions.
+ *
+ * @module agent/compaction-agent
+ */
+import { getTextContent } from '../llm/types';
+import { ContextManager, estimateTokens } from './context-manager';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** The system prompt given to the compaction model. */
+const COMPACTION_SYSTEM_PROMPT = `You are a conversation summarizer for the Nimbus CLI agent. Your job is to create a concise summary of a conversation between a user and an AI assistant that helps with cloud infrastructure and DevOps tasks.
+
+Rules:
+1. Preserve ALL important technical details: file paths, resource names, configuration values, error messages, decisions made.
+2. Preserve the user's original intent and any requirements they specified.
+3. Preserve the current state of any ongoing work (what was done, what remains).
+4. Remove conversational filler, repeated information, and verbose tool outputs.
+5. Use bullet points for clarity.
+6. Keep the summary under 2000 tokens.
+7. Structure the summary as:
+   - **User's Goal**: What the user is trying to accomplish
+   - **Key Decisions**: Important choices that were made
+   - **Work Completed**: What actions were taken and their results
+   - **Current State**: Where things stand now
+   - **Pending Items**: What still needs to be done (if any)`;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Run the compaction agent to summarize a set of messages.
+ *
+ * Splits the conversation into messages to preserve and messages to
+ * summarize (using the context manager's selection logic), sends the
+ * latter to a fast LLM for summarization, then reassembles a compacted
+ * message array.
+ *
+ * @param messages - The full conversation message array.
+ * @param contextManager - The context manager instance (provides selection logic).
+ * @param options - Compaction options (router, model, focus area).
+ * @returns The compacted messages and a result summary.
+ */
+export async function runCompaction(messages, contextManager, options) {
+    const { preserved, toSummarize } = contextManager.selectPreservedMessages(messages);
+    // Nothing to summarize -- return early
+    if (toSummarize.length === 0) {
+        const totalTokens = messages.reduce((sum, m) => sum + estimateTokens(getTextContent(m.content)), 0);
+        return {
+            messages,
+            result: {
+                originalTokens: totalTokens,
+                compactedTokens: totalTokens,
+                savedTokens: 0,
+                summaryPreserved: false,
+            },
+        };
+    }
+    // Format messages for the summarizer
+    const conversationText = formatMessagesForSummary(toSummarize);
+    const originalTokens = estimateTokens(conversationText);
+    // Build the user prompt for the summarizer
+    let userPrompt = `Please summarize the following conversation between a user and the Nimbus AI assistant:\n\n${conversationText}`;
+    if (options.focusArea) {
+        userPrompt += `\n\nPay special attention to: ${options.focusArea}`;
+    }
+    // H3: Inject current infraContext into compaction prompt so it's never omitted
+    if (options.infraContext) {
+        const ic = options.infraContext;
+        const infraLines = [];
+        if (ic.terraformWorkspace)
+            infraLines.push(`- Terraform workspace: ${ic.terraformWorkspace}`);
+        if (ic.kubectlContext)
+            infraLines.push(`- kubectl context: ${ic.kubectlContext}`);
+        if (ic.awsProfile)
+            infraLines.push(`- AWS profile: ${ic.awsProfile}`);
+        if (ic.awsRegion)
+            infraLines.push(`- AWS region: ${ic.awsRegion}`);
+        if (ic.gcpProject)
+            infraLines.push(`- GCP project: ${ic.gcpProject}`);
+        if (ic.azureSubscription)
+            infraLines.push(`- Azure subscription: ${ic.azureSubscription}`);
+        if (infraLines.length > 0) {
+            userPrompt += `\n\n## ALWAYS PRESERVE IN SUMMARY (do not omit):\n${infraLines.join('\n')}`;
+        }
+    }
+    // Call the LLM for summarization using a fast, cheap model
+    const model = options.model ?? 'haiku';
+    let summary;
+    try {
+        const response = await options.router.route({
+            messages: [
+                { role: 'system', content: COMPACTION_SYSTEM_PROMPT },
+                { role: 'user', content: userPrompt },
+            ],
+            model,
+            maxTokens: 2048,
+        });
+        summary = response.content;
+    }
+    catch {
+        // If LLM call fails, fall back to a simple extractive summary
+        summary = fallbackSummary(toSummarize);
+    }
+    // H3: Prepend infraContext block to summary so it survives compaction
+    let finalSummary = summary;
+    if (options.infraContext) {
+        const ic = options.infraContext;
+        const infraLines = [];
+        if (ic.terraformWorkspace)
+            infraLines.push(`- Terraform workspace: ${ic.terraformWorkspace}`);
+        if (ic.kubectlContext)
+            infraLines.push(`- kubectl context: ${ic.kubectlContext}`);
+        if (ic.awsProfile)
+            infraLines.push(`- AWS profile: ${ic.awsProfile}`);
+        if (ic.awsRegion)
+            infraLines.push(`- AWS region: ${ic.awsRegion}`);
+        if (ic.gcpProject)
+            infraLines.push(`- GCP project: ${ic.gcpProject}`);
+        if (ic.azureSubscription)
+            infraLines.push(`- Azure subscription: ${ic.azureSubscription}`);
+        if (infraLines.length > 0) {
+            finalSummary = `## Infrastructure Context\n${infraLines.join('\n')}\n\n${summary}`;
+        }
+    }
+    // Reassemble the compacted message array
+    const compactedMessages = contextManager.buildCompactedMessages(preserved, finalSummary);
+    const compactedTokens = compactedMessages.reduce((sum, m) => sum + estimateTokens(getTextContent(m.content)), 0);
+    return {
+        messages: compactedMessages,
+        result: {
+            originalTokens,
+            compactedTokens,
+            savedTokens: originalTokens - estimateTokens(summary),
+            summaryPreserved: true,
+        },
+    };
+}
+/**
+ * Run manual compaction from a `/compact` command.
+ *
+ * Creates a temporary context manager with default settings and
+ * delegates to {@link runCompaction}.
+ *
+ * @param messages - The full conversation message array.
+ * @param options - Compaction options plus an optional max token override.
+ * @returns The compacted messages and a result summary.
+ */
+export async function runManualCompaction(messages, options) {
+    const contextManager = new ContextManager({
+        maxContextTokens: options.maxContextTokens,
+        preserveRecentMessages: 5,
+    });
+    return runCompaction(messages, contextManager, options);
+}
+// ---------------------------------------------------------------------------
+// Internal Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Format messages into a readable conversation transcript.
+ *
+ * Each message is labelled with its role. Very long tool outputs are
+ * truncated to avoid overwhelming the summarizer model. Tool call
+ * metadata is included inline for context.
+ */
+function formatMessagesForSummary(messages) {
+    const parts = [];
+    for (const msg of messages) {
+        const role = msg.role === 'user' ? 'User' : msg.role === 'assistant' ? 'Assistant' : 'Tool';
+        const content = getTextContent(msg.content);
+        // Truncate very long tool outputs to keep summarizer input manageable
+        const truncated = content.length > 2000 ? `${content.slice(0, 2000)}... [truncated]` : content;
+        parts.push(`[${role}]: ${truncated}`);
+        // Include tool call info if present
+        if (msg.toolCalls) {
+            for (const tc of msg.toolCalls) {
+                parts.push(`  [Tool Call: ${tc.function.name}(${tc.function.arguments.slice(0, 200)})]`);
+            }
+        }
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Fallback summary when the LLM is unavailable.
+ *
+ * Produces a simple extractive summary by listing message counts
+ * and the first few user messages. This is better than nothing when
+ * the compaction model cannot be reached.
+ */
+function fallbackSummary(messages) {
+    const userMessages = messages.filter(m => m.role === 'user');
+    const assistantMessages = messages.filter(m => m.role === 'assistant');
+    const parts = ['**Conversation Summary (auto-generated)**\n'];
+    parts.push(`- ${userMessages.length} user messages and ${assistantMessages.length} assistant responses`);
+    // Extract key topics from user messages
+    for (const msg of userMessages.slice(0, 5)) {
+        const content = getTextContent(msg.content);
+        if (content.length > 0) {
+            parts.push(`- User asked: "${content.slice(0, 150)}${content.length > 150 ? '...' : ''}"`);
+        }
+    }
+    return parts.join('\n');
+}