@epoch-ai/cli 2.2.4 → 2.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "2.2.4",
+  "version": "2.2.6",
   "name": "@epoch-ai/cli",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
     "db": "bun drizzle-kit"
   },
   "bin": {
-    "epochcli": "bin/epochcli"
+    "epochcli": "bin/epochcli.cjs"
   },
   "randomField": "this-is-a-random-value-12345",
   "exports": {

package/script/publish.ts

@@ -27,7 +27,7 @@ await Bun.file(`./dist/${pkg.name}/package.json`).write(
     {
       name: pkg.name,
       bin: {
-        epochcli: `./bin/epochcli`,
+        epochcli: `./bin/epochcli.cjs`,
       },
       scripts: {
         postinstall: "node ./postinstall.mjs",
@@ -41,16 +41,14 @@ await Bun.file(`./dist/${pkg.name}/package.json`).write(
   ),
 )
 
-const tasks = Object.entries(binaries).map(async ([name]) => {
+for (const [name] of Object.entries(binaries)) {
   const pkgDir = `./dist/${name}`
   if (process.platform !== "win32") {
     await $`chmod -R 755 .`.cwd(pkgDir)
   }
-  await $`bun pm pack`.cwd(pkgDir)
-  await $`npm publish *.tgz --access public --tag latest`.cwd(pkgDir).nothrow()
-})
-await Promise.all(tasks)
-await $`cd ./dist/${pkg.name} && bun pm pack && npm publish *.tgz --access public --tag latest`.nothrow()
+  await $`npm publish --access public --tag latest`.cwd(pkgDir).nothrow()
+}
+await $`cd ./dist/${pkg.name} && npm publish --access public --tag latest`.nothrow()
 
 // const image = "ghcr.io/benjamesmurray/epoch-cli"
 // const platforms = "linux/amd64,linux/arm64"

package/src/cli/cmd/tui/component/prompt/index.tsx

@@ -1219,7 +1219,19 @@ export function Prompt(props: PromptProps) {
           />
         </box>
         <box flexDirection="row" justifyContent="space-between">
-          <Show when={status().type !== "idle"} fallback={props.hint ?? <text />}>
+          <Show 
+            when={status().type !== "idle"} 
+            fallback={
+              <box flexDirection="row" gap={2}>
+                {props.hint ?? <text />}
+                <Show when={store.mode === "normal"}>
+                  <text fg={theme.text}>
+                    {keybind.print("yolo_toggle")} <span style={{ fg: theme.textMuted }}>mode</span>
+                  </text>
+                </Show>
+              </box>
+            }
+          >
             <box
               flexDirection="row"
               gap={1}
@@ -1307,7 +1319,7 @@ export function Prompt(props: PromptProps) {
                     <Match when={usage()}>
                       {(item) => (
                         <text fg={theme.textMuted} wrapMode="none">
-                          {[item().context, item().cost].filter(Boolean).join(" · ")}
+                          {item().context}
                         </text>
                       )}
                     </Match>

package/src/cli/cmd/tui/feature-plugins/sidebar/context.tsx

@@ -1,34 +1,46 @@
 import type { AssistantMessage } from "@epoch-ai/sdk/v2"
 import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@epoch-ai/plugin/tui"
-import { createMemo } from "solid-js"
+import { createMemo, Show } from "solid-js"
 
 const id = "internal:sidebar-context"
 
-const money = new Intl.NumberFormat("en-US", {
-  style: "currency",
-  currency: "USD",
-})
-
 function View(props: { api: TuiPluginApi; session_id: string }) {
   const theme = () => props.api.theme.current
   const msg = createMemo(() => props.api.state.session.messages(props.session_id))
-  const cost = createMemo(() => msg().reduce((sum, item) => sum + (item.role === "assistant" ? item.cost : 0), 0))
 
   const state = createMemo(() => {
     const last = msg().findLast((item): item is AssistantMessage => item.role === "assistant" && item.tokens.output > 0)
     if (!last) {
       return {
         tokens: 0,
-        percent: null,
+        usable: null,
+        limit: null,
+        margin: null,
       }
     }
 
     const tokens =
       last.tokens.input + last.tokens.output + last.tokens.reasoning + last.tokens.cache.read + last.tokens.cache.write
     const model = props.api.state.provider.find((item) => item.id === last.providerID)?.models[last.modelID]
+    
+    let limit = null
+    let usable = null
+    let margin = null
+
+    if (model) {
+      limit = model.limit.context
+      if (limit > 0) {
+        const maxOutput = Math.min(model.limit.output || 32000, 32000)
+        margin = Math.min(1024, Math.max(500, maxOutput))
+        usable = model.limit.input ? model.limit.input : limit - margin
+      }
+    }
+
     return {
       tokens,
-      percent: model?.limit.context ? Math.round((tokens / model.limit.context) * 100) : null,
+      usable,
+      limit,
+      margin,
     }
   })
 
@@ -38,8 +50,15 @@ function View(props: { api: TuiPluginApi; session_id: string }) {
         <b>Context</b>
       </text>
       <text fg={theme().textMuted}>{state().tokens.toLocaleString()} tokens</text>
-      <text fg={theme().textMuted}>{state().percent ?? 0}% used</text>
-      <text fg={theme().textMuted}>{money.format(cost())} spent</text>
+      <Show when={state().usable !== null}>
+        <text fg={theme().textMuted}>{state().usable!.toLocaleString()} usable</text>
+      </Show>
+      <Show when={state().limit !== null}>
+        <text fg={theme().textMuted}>{state().limit!.toLocaleString()} limit</text>
+      </Show>
+      <Show when={state().margin !== null}>
+        <text fg={theme().textMuted}>{state().margin!.toLocaleString()} margin</text>
+      </Show>
     </box>
   )
 }

package/src/cli/cmd/tui/feature-plugins/sidebar/footer.tsx

@@ -64,9 +64,9 @@ function View(props: { api: TuiPluginApi }) {
         <span style={{ fg: theme().text }}>{path().name}</span>
       </text>
       <text fg={theme().textMuted}>
-        <span style={{ fg: theme().success }}>•</span> <b>Open</b>
+        <span style={{ fg: theme().success }}>•</span> <b>Epoch</b>
         <span style={{ fg: theme().text }}>
-          <b>Code</b>
+          <b> CLI</b>
         </span>{" "}
         <span>{props.api.app.version}</span>
       </text>

package/src/cli/cmd/tui/routes/home.tsx

@@ -8,11 +8,21 @@ import { useRouteData } from "@tui/context/route"
 import { usePromptRef } from "../context/prompt"
 import { useLocal } from "../context/local"
 import { TuiPluginRuntime } from "../plugin"
+import { execSync } from "child_process"
 
 // TODO: what is the best way to do this?
 let once = false
+
+let userName = "there"
+try {
+  const output = execSync("git config --global user.name", { stdio: "pipe" }).toString().trim()
+  if (output) userName = output
+} catch {
+  // Ignore errors (e.g., git not found, config not set)
+}
+
 const placeholder = {
-  normal: ["Fix a TODO in the codebase", "What is the tech stack of this project?", "Fix broken tests"],
+  normal: [`Hi ${userName}, let's go!`],
   shell: ["ls -la", "git status", "pwd"],
 }
 

package/src/cli/cmd/tui/routes/session/sidebar.tsx

@@ -56,9 +56,9 @@ export function Sidebar(props: { sessionID: string; overlay?: boolean }) {
         <box flexShrink={0} gap={1} paddingTop={1}>
           <TuiPluginRuntime.Slot name="sidebar_footer" mode="single_winner" session_id={props.sessionID}>
             <text fg={theme.textMuted}>
-              <span style={{ fg: theme.success }}>•</span> <b>Open</b>
+              <span style={{ fg: theme.success }}>•</span> <b>Epoch</b>
               <span style={{ fg: theme.text }}>
-                <b>Code</b>
+                <b> CLI</b>
               </span>{" "}
               <span>{Installation.VERSION}</span>
             </text>

package/src/project/bootstrap.ts

@@ -10,9 +10,15 @@ import { Bus } from "../bus"
 import { Command } from "../command"
 import { Instance } from "./instance"
 import { Log } from "@/util/log"
+import { initProjectFiles } from "./init-files"
 
 export async function InstanceBootstrap() {
   Log.Default.info("bootstrapping", { directory: Instance.directory })
+  
+  if (Instance.project.vcs === "git" && Instance.worktree !== "/") {
+    await initProjectFiles(Instance.directory, Instance.worktree)
+  }
+
   await Plugin.init()
   Format.init()
   await LSP.init()

package/src/project/init-files.ts

@@ -0,0 +1,328 @@
+import fs from "fs/promises"
+import path from "path"
+import { zodToJsonSchema } from "zod-to-json-schema"
+import { Config } from "../config/config"
+import { Log } from "../util/log"
+
+const log = Log.create({ service: "project-init" })
+
+const AGENTS_MD_CONTENT = `# Epoch CLI Agent Guidelines
+
+## 1. Mandatory Workflows
+- **\`mcpx\` (Unified MCP Interface)**: Use for ALL MCP interactions (spec, map, ground, github).
+    - **Adding Servers**: When asked to install or configure a new MCP server, you MUST follow the SOP defined in \`docs/MCP_config_guide.md\`.
+    - **Syntax**: Pass arguments via standard flags, \`key=value\` strings, or structured JSON.
+    - **Self-Discovery**: Use \`tool="--help"\` or \`args=["--help"]\` to inspect servers/tools.
+- **\`spec\` (State Management)**: Maintain project state via \`mcpx\` server="spec".
+    - **Linear Progression**: \`sc_init\` -> \`write Specification.md\` -> \`sc_approve\` -> \`write Tasks.json\` -> \`sc_approve\` -> \`Build\`.
+    - **Arguments**: \`sc_init\` MANDATES the \`name\` parameter (e.g., \`flags: {"name": "my-feature"}\`). \`sc_plan\` and \`sc_approve\` take NO arguments. \`sc_todo_*\` requires \`--id\`.
+- **\`map\` (Architectural Discovery)**: Use \`mcpx\` server="map" for navigation. Prefer \`pm_status\` and \`pm_query\` over manual \`ls\` or \`glob\`.
+
+## 2. Enforcement
+- **Drafting Wall**: All template tags in \`Specification.md\` must be cleared and \`template_tags_present\` set to \`false\` before implementation.
+- **Orientation**: Trust the provided context. If \`ORIENTATION_REQUIREMENTS: SATISFIED\` is present, do not repeat discovery tools.
+- **YOLO Mode**: Proceed autonomously until \`task_complete\` is called.
+
+## 3. Subagent Guardrails
+- **No State Mutation**: Subagents (e.g., \`@explore\`, \`@general\`) are STRICTLY FORBIDDEN from calling \`sc_init\` or \`sc_approve\`. Only the primary \`plan\` or \`build\` agent may mutate the global project lifecycle state.
+- **Architectural Discovery**: Subagents MUST prioritize \`mcpx map\` tools (\`pm_query\` for context, \`pm_fetch_symbol\` for precise code extraction) to navigate the codebase efficiently. Avoid wide \`glob\` or \`read\` loops on large files.
+`
+
+const MCP_CONFIG_GUIDE_CONTENT = `# Guide: Setting Up MCP Servers with \`mcpx-rust\`
+
+This guide explains how to configure Model Context Protocol (MCP) servers within this project using the \`mcpx-rust\` CLI utility. By using \`mcpx\`, we reduce prompt bloat by replacing massive JSON schemas with a single, discoverable CLI interface.
+
+## 1. Installation
+
+\`mcpx-rust\` is the Rust-based binary used in this project to turn MCP servers into composable shell commands.
+
+\`\`\`bash
+# Via Cargo
+cargo install mcpx-rust
+\`\`\`
+
+## 2. Registering Servers
+
+\`mcpx-rust\` stores its configuration in \`~/.config/mcpx/config.toml\`. You must edit this file manually to add or modify servers.
+
+### Manual Configuration
+Add entries to the \`[mcp_servers]\` section in \`~/.config/mcpx/config.toml\`:
+
+\`\`\`toml
+[mcp_servers.map]
+command = "project-map-cli-rust"
+args = ["mcp"]
+
+[mcp_servers.spec]
+command = "deliver-cli"
+args = ["mcp"]
+
+[mcp_servers.github]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-github"]
+env = { GITHUB_TOKEN = "\${GITHUB_TOKEN}" }
+\`\`\`
+
+## 3. \`epochcli\` / \`gemini-cli\` Integration
+
+To enable \`mcpx\` integration, update your configuration file (e.g., \`.epochcli/epochcli.jsonc\` or \`.gemini/settings.json\`):
+
+\`\`\`jsonc
+{
+  "mcpx": {
+    "enabled": true,
+    "binaryPath": "mcpx-rust" // Optional: defaults to 'mcpx-rust'
+  },
+  "mcp": {} // Leave empty to disable standard schema-based MCP tools
+}
+\`\`\`
+
+When enabled, the CLI will only expose a single \`mcpx\` tool to the LLM. The agent will discover capabilities dynamically by running \`mcpx <server> --help\`.
+
+## 4. Usage and Composition
+
+Once configured, tools can be called using standard shell composition:
+
+\`\`\`bash
+# List all servers
+mcpx-rust list
+
+# List tools for a server
+mcpx-rust github
+
+# Inspect a specific tool's schema
+mcpx-rust github search-repositories --help
+
+# Call a tool and pipe to jq
+mcpx-rust github search-repositories query=mcp --json | jq -r '.content[0].text'
+\`\`\`
+
+Note: \`mcpx-rust\` uses \`key=value\` syntax for positional arguments or standard \`--flag value\` syntax depending on the tool's implementation.
+
+## 5. Project Servers
+
+The following project-specific servers are pre-configured. Agents should use the unified \`mcpx\` tool for all operations:
+
+- **\`spec\`**: Management of specification-driven development.
+    - \`mcpx spec sc_status\`: View project health and next steps.
+    - \`mcpx spec sc_todo_start\`: Mark a task as active.
+- **\`map\`**: Architectural mapping and symbol analysis.
+    - \`mcpx map pm_query\`: Search for symbols or get file context.
+    - \`mcpx map pm_plan\`: Analyze the architectural impact of a change.
+- **\`ground\`**: Synthesis of behavioral rules and operational facts.
+    - \`mcpx ground gt_status\`: Check current project rules.
+    - \`mcpx ground gt_refresh\`: Force a refresh of the project constitution.
+
+## 6. Agent SOP: Adding a New Server
+
+When an agent is instructed to add or install a new MCP server, it MUST follow this sequence to ensure the server is properly registered and discoverable:
+
+1.  **Identify the Server**: Determine the correct command (e.g., \`npx -y package-name\`) or binary path for the requested MCP server.
+2.  **Register the Server**: Update the configuration in \`~/.config/mcpx/config.toml\`.
+    - *Note*: Agents must use \`echo\` or \`cat <<EOF\` via \`run_shell_command\` to modify this file, as it lives outside the standard workspace directory.
+3.  **Verify Installation**: Run \`mcpx-rust list\` and \`mcpx-rust <new_server> --help\` to ensure the routing engine recognizes the new server and the tool schema is accessible.
+4.  **Update Project Knowledge**: Update \`AGENTS.md\` (or the relevant instruction file) with a brief summary of the new server's capabilities and its \`mcpx\` syntax so that future agent turns can utilize the new tools.
+`
+
+const MODEL_CONFIG_GUIDE_CONTENT = `# Model Configuration Guide
+
+Epoch CLI utilizes a **Dual-Model Architecture** optimized for high-performance coding and reliable background supervision. This environment uses a unified proxy architecture (**llama-swap**) to manage model transitions efficiently.
+
+## 1. Unified Architecture (llama-swap)
+
+Instead of managing separate URLs and ports, all models are served through a single transparent proxy on one port. This allows the system to dynamically swap models in VRAM as needed while maintaining a consistent client configuration.
+
+*   **Unified API Endpoint:** \`http://localhost:8085/v1\`
+*   **Protocol:** OpenAI Compatible
+*   **Authentication:** Shared API Key (e.g., \`2250\`)
+
+## 2. Configuration (\`epochcli.jsonc\`)
+
+You can configure Epoch CLI to use either a single unified endpoint for both main and side roles, or a dual-model configuration that leverages the \`llama-swap\` proxy.
+
+### Option A: Single Endpoint Configuration (Recommended for High Context)
+
+This setup uses one model for both roles. It is ideal for maximizing the context window (e.g., 64k) and eliminating the 15-20 second "cold start" delay associated with swapping models.
+
+\`\`\`jsonc
+{
+  "model": "local-unified/qwen-unified",
+  "side_model": "local-unified/qwen-unified",
+  "provider": {
+    "local-unified": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Local Unified (Qwen 64k)",
+      "options": {
+        "baseURL": "http://localhost:8085/v1",
+        "apiKey": "2250"
+      },
+      "models": {
+        "qwen-unified": {
+          "name": "Qwen Unified 64k",
+          "limit": { "context": 64000, "output": 4096 }
+        }
+      }
+    }
+  }
+}
+\`\`\`
+
+### Option B: Dual-Model Configuration (llama-swap)
+
+This setup defines separate providers for main and side roles. The proxy handles routing based on the model ID. This is useful when you want a dedicated smaller model for clerk duties to save compute or when specific roles require different model capabilities.
+
+\`\`\`jsonc
+{
+  "model": "local-main/qwen3.6-35b-a3b-coding", 
+  "side_model": "local-side/nemotron-3-nano",
+  "provider": {
+    "local-main": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Local Main (Coding)",
+      "options": {
+        "baseURL": "http://localhost:8085/v1",
+        "apiKey": "2250"
+      },
+      "models": {
+        "qwen3.6-35b-a3b-coding": { 
+          "name": "Qwen 3.6 35B Coding",
+          "limit": { "context": 64000, "output": 4096 }
+        }
+      }
+    },
+    "local-side": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Local Side (Clerk)",
+      "options": {
+        "baseURL": "http://localhost:8085/v1",
+        "apiKey": "2250"
+      },
+      "models": {
+        "nemotron-3-nano": { 
+          "name": "Nemotron 3 Nano",
+          "limit": { "context": 32000, "output": 2048 }
+        }
+      }
+    }
+  }
+}
+\`\`\`
+
+### Switching Between Modes
+
+To switch modes, simply update the \`model\`, \`side_model\`, and \`provider\` fields in your \`.epochcli/epochcli.jsonc\` file to match the desired configuration block. The CLI will automatically pick up the changes on the next execution.
+
+## 3. How Epoch CLI Identifies Models
+
+Epoch CLI uses **keyword matching** on the Model ID string to apply specific architectural optimizations. You do not need to manually configure prompts or behaviors for different models as long as the ID is named correctly:
+
+*   **Qwen Optimized:** If the ID contains \`"qwen"\` (e.g., \`qwen3.6-35b-a3b-coding\`), the CLI automatically sets the temperature to \`0.55\` and Top-P to \`1.0\`.
+*   **Gemma Optimized:** If the ID contains \`"gemma-4"\`, the CLI enables reasoning token injection (\`<|think|>\`), specialized system prompts, and the Three-Stage Sanitizer to repair potential JSON errors.
+
+## 4. Operational Considerations
+
+### The "Cold Start" (Model Swapping)
+The environment uses a **SWAP approach** to maximize VRAM for high-context models. Only one model is active in memory at a time.
+*   **Instant Response:** If you request the model that is already "hot" in memory.
+*   **Swap Delay:** If you request a model that is currently swapped out, the proxy will load it automatically. This adds a **15–20 second delay** to the first request.
+
+### Context Persistence & TTL
+Models stay active in VRAM for **60 minutes** of inactivity before being automatically unloaded. This ensures subsequent requests within the same hour are nearly instantaneous.
+
+## 5. Monitoring & Maintenance
+
+*   **Dashboard:** You can monitor which model is currently active and view proxy status at \`http://localhost:8085/ui\`.
+*   **Restart Stack:** If you need to restart the entire dual-model stack, use the provided launch script:
+    \`\`\`bash
+    /home/llm/utils/launch/launch-dual.sh
+    \`\`\`
+`
+
+const DEFAULT_EPOCHCLI_JSONC = `{
+  "$schema": "./config.json",
+  "model": "local-unified/qwen-unified",
+  "side_model": "local-unified/qwen-unified",
+  "provider": {
+    "local-unified": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Local Unified (Qwen 64k)",
+      "options": {
+        "baseURL": "http://localhost:8085/v1",
+        "apiKey": "2250"
+      },
+      "models": {
+        "qwen-unified": {
+          "name": "Qwen Unified 64k",
+          "limit": {
+            "context": 64000,
+            "output": 4096
+          }
+        }
+      }
+    }
+  },
+  "permission": {
+    "edit": {
+      "packages/opencode/migration/*": "deny"
+    }
+  },
+  "mcpx": {
+    "enabled": true
+  }
+}
+`
+
+export async function initProjectFiles(directory: string, worktree: string) {
+  try {
+    const epochcliDir = path.join(worktree, ".epochcli")
+    
+    try {
+      await fs.access(epochcliDir)
+      return // Already initialized
+    } catch {
+      // Doesn't exist, proceed with initialization
+    }
+
+    log.info("Initializing new project files", { worktree })
+
+    // Create .epochcli directory
+    await fs.mkdir(epochcliDir, { recursive: true })
+
+    // Generate JSON Schema
+    const schema = zodToJsonSchema(Config.Info, {
+      name: "Config",
+      $refStrategy: "none",
+    })
+    
+    // Write config.json (schema)
+    await fs.writeFile(
+      path.join(epochcliDir, "config.json"),
+      JSON.stringify(schema, null, 2)
+    )
+
+    // Write default epochcli.jsonc
+    await fs.writeFile(
+      path.join(epochcliDir, "epochcli.jsonc"),
+      DEFAULT_EPOCHCLI_JSONC
+    )
+
+    // Setup docs
+    const docsDir = path.join(epochcliDir, "docs")
+    await fs.mkdir(docsDir, { recursive: true })
+    await fs.writeFile(path.join(docsDir, "MCP_config_guide.md"), MCP_CONFIG_GUIDE_CONTENT)
+    await fs.writeFile(path.join(docsDir, "model_config.md"), MODEL_CONFIG_GUIDE_CONTENT)
+
+    // Setup AGENTS.md in the current directory if it doesn't exist
+    const agentsFile = path.join(directory, "AGENTS.md")
+    try {
+      await fs.access(agentsFile)
+    } catch {
+      await fs.writeFile(agentsFile, AGENTS_MD_CONTENT)
+      log.info("Created AGENTS.md", { path: agentsFile })
+    }
+
+    log.info("Project initialized successfully", { dir: epochcliDir })
+  } catch (error) {
+    log.error("Failed to initialize project files", { error })
+  }
+}

package/src/session/overflow.ts

@@ -30,6 +30,5 @@ export function isOverflow(input: {
           (input.tokens.reasoning ?? 0) +
           ((input.tokens.cache?.read ?? 0) + (input.tokens.cache?.write ?? 0)))
 
-  console.log(`[OverflowCheck] tokens=${count} usable=${usable} (limit=${context} margin=${safetyMargin})`)
   return count >= usable
 }