echospace 0.1.0-alpha.3 → 0.1.0-alpha.6

package/README.md

@@ -6,54 +6,45 @@
 
 <p align="center"><strong>The open-source, local-first prompt debugging workspace for LLM developers.</strong></p>
 
-Debug, iterate, and manage your prompts across OpenAI, Anthropic, and Google — all from your terminal. No cloud, no accounts, no lock-in.
+<p align="center">
+  Debug, iterate, and manage your prompts across multiple LLM providers — all from your terminal.<br/>
+  No cloud. No accounts. No lock-in.
+</p>
 
 ---
 
 ## Why EchoSpace?
 
-### Local First
-
-All data stored as `.echo` files on disk. No cloud, no accounts. Your prompts stay on your machine, version-controlled alongside your code.
-
-### Open Source & Customizable
+Prompt engineering is iterative, but most tools make you choose between a polished UI and full control over your data. EchoSpace gives you both: a browser-based workspace that runs entirely on your machine, stores conversations as plain files you can version-control, and works with any OpenAI-compatible provider out of the box.
 
-MIT-licensed. Pluggable provider adapters (OpenAI, Anthropic, Google). YAML-based config with `${ENV_VAR}` substitution.
-
-### CLI & SDK
-
-`npx echospace@alpha` to launch. Core TypeScript modules (`parseEcho`, `serializeEcho`, `smartParse`, provider registry) can be imported as a library for building your own tools.
+- **Local-first** — all data stored as `.echo` files on disk, version-controlled alongside your code
+- **Open source** — MIT-licensed, pluggable provider adapters, `${ENV_VAR}` substitution in config
+- **CLI & library** — `npx echospace@alpha` to launch; core modules (`parseEcho`, `serializeEcho`, `smartParse`, provider registry) are importable as a library
 
 ---
 
 ## Features
 
-- **Multi-provider streaming** — OpenAI, Anthropic, Google Gemini with SSE streaming
-- **Universal `.echo` format** — NDJSON-based, human-readable conversation protocol
-- **Smart Paste** — auto-detects and converts conversations from ChatGPT, Claude, Gemini, or raw text
-- **Timeline / history with branching** — revert to any point in a conversation
-- **Tool use support** — `tool_call` / `tool_result` parts
-- **Token counting** — tiktoken-based token estimation
-- **Image support** — inline images in messages (base64 or URL)
+- **Multi-provider streaming** — SSE streaming across all configured providers (OpenAI, Anthropic, Google, or any OpenAI-compatible gateway)
+- **Universal `.echo` format** — NDJSON-based, human-readable conversation protocol designed for diffing and version control
+- **Smart Paste** — auto-detects and converts conversation exports from major LLM platforms or raw text
+- **Timeline & branching** — revert to any point in a conversation, fork branches, compare results
+- **Tool use support** — first-class `tool_call` / `tool_result` message parts
+- **Token counting** — tiktoken-based token estimation shown in real time
+- **Image support** — inline images in messages via base64 or URL
 - **Per-conversation model settings** — temperature, max_tokens, top_p, response_format, JSON schema, tools
 
 ---
 
-## Quick Start
-
-### 1. Install skills
+## Getting Started
 
-EchoSpace ships with agent skills that work with any coding agent — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenAI Codex](https://openai.com/index/codex/), or any tool that supports the skills/SKILL.md convention.
+### 1. Initialize
 
 ```bash
-npx skills add https://github.com/stonexer/echospace/tree/master/skills/echospace
+npx echospace@alpha init
 ```
 
-### 2. Configure providers
-
-```bash
-npx echospace init
-```
+The interactive setup wizard configures your provider and API key:
 
 ```
 ◆ Which LLM service do you use?
@@ -67,11 +58,14 @@ npx echospace init
 │ sk-xxxxxxxx
 
 ✓ Config saved to ~/.echospace/config.yaml
-```
 
-Or use the agent skill: `/echospace:init`
+◆ Install agent skills for your coding agent? (Claude Code, Codex, etc.)
+│ ● Yes / ○ No
 
-### 3. Launch
+✓ Skills installed!
+```
+
+### 2. Launch
 
 ```bash
 npx echospace@alpha
@@ -80,32 +74,25 @@ npx echospace@alpha
 Or install globally:
 
 ```bash
-pnpm add -g echospace
+pnpm add -g echospace@alpha
 echospace ./my-project
 ```
 
-This will:
+EchoSpace will:
 
 1. Create a `.echo/` workspace in your project directory
 2. Start a local server and open the UI in your browser
 
 ```
-  ╔══════════════════════════════════════╗
-  ║           EchoSpace v0.1.0          ║
-  ╠══════════════════════════════════════╣
-  ║  Workspace: /my-project/.echo        ║
-  ║  URL:       http://localhost:3240    ║
-  ╚══════════════════════════════════════╝
+  ██████████████
+  ██          ██   EchoSpace v0.1.0
+  ██  ██████  ██
+  ██  ██  ██  ██   Workspace  /my-project/.echo
+  ██  ██████  ██   URL        http://localhost:3240
+  ██          ██
+  ██████████████
 ```
 
-### Available Skills
-
-| Skill | Description |
-|-------|-------------|
-| `/echospace:init` | Interactive setup wizard — select providers, enter API keys, generate config |
-| `/echospace:export` | Convert conversation files (OpenAI, Anthropic, Google, Helicone, raw text) into `.echo` format |
-| `/echospace:integrate` | Integrate `.echo` export into your own app |
-
 ### CLI Options
 
 ```
@@ -116,6 +103,26 @@ echospace [workdir] [options]
   --no-open           Don't open browser automatically
 ```
 
+### Agent Skills
+
+| Skill | Description |
+| --- | --- |
+| `/echospace-export` | Convert conversation exports from major LLM platforms into `.echo` format |
+| `/echospace-integrate` | Integrate a `.echo` export into your own app |
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+| --- | --- |
+| Frontend | React 19, Tailwind CSS v4, Zustand, CodeMirror |
+| Backend | Hono, Node.js |
+| Build | Vite, tsup, TypeScript 5 |
+| Testing | Vitest |
+| Tokenization | tiktoken |
+| Package manager | pnpm |
+
 ---
 
 ## The `.echo` Format
@@ -134,7 +141,7 @@ Each message can contain multiple part types: `text`, `thinking`, `tool_call`, `
 
 ## Configuration
 
-On first launch, EchoSpace creates `~/.echospace/config.yaml`. Fill in the `api_key` for the providers you want to use — unconfigured providers are automatically ignored.
+Run `npx echospace@alpha init` to create `~/.echospace/config.yaml`, or edit it manually:
 
 ```yaml
 providers:
@@ -165,9 +172,26 @@ providers:
       - gemini-2.5-pro
       - gemini-2.5-flash
       - gemini-2.0-flash
+
+  - name: vercel-ai-gateway
+    type: openai
+    api_key: xxxxxxxx
+    base_url: https://ai-gateway.vercel.sh/v1
+    models:
+      - anthropic/claude-sonnet-4-6
+      - openai/gpt-4.1
+      - google/gemini-2.5-pro
+
+  # Custom OpenAI-compatible gateway
+  - name: custom
+    type: openai          # or: anthropic, google
+    api_key: xxxxxxxx
+    base_url: https://my-proxy.example.com/v1
+    models:
+      - my-model-name
 ```
 
-> **Tip:** `${ENV_VAR}` syntax is also supported for API keys — they are resolved from your environment at runtime. `.env` files in your project directory are auto-loaded.
+> **Tip:** `${ENV_VAR}` syntax is supported for API keys — values are resolved from your environment at runtime. `.env` files in your project directory are auto-loaded.
 
 ---
 
@@ -185,6 +209,7 @@ pnpm build        # Build for production
 pnpm typecheck    # Type-check without emitting
 pnpm lint         # ESLint
 pnpm format       # Prettier
+pnpm test         # Run tests
 ```
 
 ---

package/dist/cli/index.js

@@ -330,20 +330,23 @@ var googleAdapter = {
 };
 
 // src/core/providers/openai.ts
-function toOpenAIMessage(msg) {
-  const result = { role: msg.role };
+function toOpenAIMessages(msg) {
   const textParts = msg.parts.filter((p2) => p2.type === "text");
   const toolCalls = msg.parts.filter((p2) => p2.type === "tool_call");
   const toolResults = msg.parts.filter((p2) => p2.type === "tool_result");
   const thinkingParts = msg.parts.filter((p2) => p2.type === "thinking");
   if (msg.role === "tool" && toolResults.length > 0) {
-    const tr = toolResults[0];
-    result.content = typeof tr.output === "string" ? tr.output : JSON.stringify(tr.output);
-    result.tool_call_id = tr.tool_call_id;
-    return result;
+    return toolResults.map((tr) => ({
+      role: "tool",
+      tool_call_id: tr.tool_call_id,
+      content: typeof tr.output === "string" ? tr.output : JSON.stringify(tr.output)
+    }));
   }
   if (msg.role === "assistant") {
-    result.content = textParts.map((p2) => p2.text).join("") || null;
+    const result = {
+      role: "assistant",
+      content: textParts.map((p2) => p2.text).join("") || null
+    };
     if (thinkingParts.length > 0) {
       result.reasoning_content = thinkingParts.map((p2) => p2.text).join("");
     }
@@ -357,10 +360,9 @@ function toOpenAIMessage(msg) {
         }
       }));
     }
-    return result;
+    return [result];
   }
-  result.content = textParts.map((p2) => p2.text).join("");
-  return result;
+  return [{ role: msg.role, content: textParts.map((p2) => p2.text).join("") }];
 }
 var openaiAdapter = {
   type: "openai",
@@ -369,7 +371,7 @@ var openaiAdapter = {
     const url = `${baseUrl.replace(/\/$/, "")}/chat/completions`;
     const body = {
       model: settings.model ?? config.models[0],
-      messages: messages.map(toOpenAIMessage),
+      messages: messages.flatMap(toOpenAIMessages),
       stream: true
     };
     if (settings.temperature != null) body.temperature = settings.temperature;
@@ -592,7 +594,7 @@ function normalizeMessage(message) {
   const needsPartNormalization = msg.parts.some((p2) => {
     if (p2.type !== "tool_result") return false;
     const r = p2;
-    return !r.tool_call_id && (r.id || r.tool_use_id);
+    return !r.tool_call_id && (r.id || r.tool_use_id || r.call_id);
   });
   if (needsPartNormalization) {
     msg = {
@@ -600,9 +602,9 @@ function normalizeMessage(message) {
       parts: msg.parts.map((p2) => {
         if (p2.type !== "tool_result") return p2;
         const r = p2;
-        if (!r.tool_call_id && (r.id || r.tool_use_id)) {
-          const { id, tool_use_id, ...rest } = r;
-          return { ...rest, tool_call_id: id ?? tool_use_id };
+        if (!r.tool_call_id && (r.id || r.tool_use_id || r.call_id)) {
+          const { id, tool_use_id, call_id, ...rest } = r;
+          return { ...rest, tool_call_id: id ?? tool_use_id ?? call_id };
         }
         return p2;
       })
@@ -864,6 +866,7 @@ function startServer(options) {
 
 // src/cli/init.ts
 import * as p from "@clack/prompts";
+import { execSync } from "child_process";
 import { homedir } from "os";
 import path4 from "path";
 var CONFIG_DIR = path4.join(homedir(), ".echospace");
@@ -940,7 +943,7 @@ async function runInit() {
     const baseUrl = await p.text({
       message: "Base URL (e.g. https://my-proxy.example.com/v1):",
       validate: (v) => {
-        if (!v.trim()) return "URL is required";
+        if (!v?.trim()) return "URL is required";
         try {
           new URL(v.trim());
         } catch {
@@ -1004,11 +1007,25 @@ async function runInit() {
   saveConfig(CONFIG_DIR, config);
   const configPath = path4.join(CONFIG_DIR, "config.yaml");
   p.log.success(`Config saved to ${configPath}`);
-  p.outro("You're all set! Run `npx echospace` to start.");
+  const installSkills = await p.confirm({
+    message: "Install agent skills for Claude Code / Cursor? (npx skills add stonexer/echospace)"
+  });
+  if (installSkills && !isCancel2(installSkills)) {
+    const s = p.spinner();
+    s.start("Installing skills...");
+    try {
+      execSync("npx skills add stonexer/echospace", { stdio: "pipe" });
+      s.stop("Skills installed!");
+    } catch {
+      s.stop("Failed to install skills");
+      p.log.warn("Run manually: npx skills add stonexer/echospace");
+    }
+  }
+  p.outro("You're all set! Run `npx echospace@alpha` to start.");
 }
 
 // src/cli/index.ts
-var VERSION = "0.1.0-alpha.3";
+var VERSION = "0.1.0-alpha.6";
 var CONFIG_DIR2 = path5.join(homedir2(), ".echospace");
 function loadEnvFile(dir) {
   const envPath = path5.join(dir, ".env");
@@ -1027,19 +1044,23 @@ function loadEnvFile(dir) {
   }
 }
 var program = new Command();
-program.name("echospace").description("The best open-source local prompt debugging tool").version(VERSION).argument("[workdir]", "Workspace directory", ".").option("-p, --port <port>", "Port to serve on").option("--no-open", "Don't open browser automatically").action(async (workdir, options) => {
-  const baseDir = path5.resolve(process.cwd(), workdir);
-  const workspaceDir = path5.join(baseDir, ".echo");
-  loadEnvFile(baseDir);
-  loadEnvFile(process.cwd());
-  if (!fs3.existsSync(workspaceDir)) {
-    fs3.mkdirSync(workspaceDir, { recursive: true });
-  }
-  fs3.mkdirSync(CONFIG_DIR2, { recursive: true });
-  ensureConfig(CONFIG_DIR2);
-  const port = options.port ? parseInt(options.port, 10) : await getPort({ port: portNumbers(3240, 3249) });
-  const url = `http://localhost:${port}`;
-  console.log(`
+program.name("echospace").description("The best open-source local prompt debugging tool").version(VERSION).argument("[workdir]", "Workspace directory", ".").option("-p, --port <port>", "Port to serve on").option(
+  "-d, --dir <path>",
+  "Open this directory directly as the workspace (skips the .echo subdir)"
+).option("--no-open", "Don't open browser automatically").action(
+  async (workdir, options) => {
+    const baseDir = path5.resolve(process.cwd(), workdir);
+    const workspaceDir = options.dir ? path5.resolve(process.cwd(), options.dir) : path5.join(baseDir, ".echo");
+    loadEnvFile(baseDir);
+    loadEnvFile(process.cwd());
+    if (!fs3.existsSync(workspaceDir)) {
+      fs3.mkdirSync(workspaceDir, { recursive: true });
+    }
+    fs3.mkdirSync(CONFIG_DIR2, { recursive: true });
+    ensureConfig(CONFIG_DIR2);
+    const port = options.port ? parseInt(options.port, 10) : await getPort({ port: portNumbers(3240, 3249) });
+    const url = `http://localhost:${port}`;
+    console.log(`
   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588
   \u2588\u2588          \u2588\u2588   EchoSpace v${VERSION}
   \u2588\u2588  \u2588\u2588\u2588\u2588\u2588\u2588  \u2588\u2588
@@ -1048,17 +1069,18 @@ program.name("echospace").description("The best open-source local prompt debuggi
   \u2588\u2588          \u2588\u2588
   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588
 `);
-  const isDev = process.env.NODE_ENV !== "production" && import.meta.url.includes("/src/");
-  startServer({ port, workspaceDir, configDir: CONFIG_DIR2, dev: isDev });
-  if (options.open) {
-    await open(`http://localhost:${port}`);
+    const isDev = process.env.NODE_ENV !== "production" && import.meta.url.includes("/src/");
+    startServer({ port, workspaceDir, configDir: CONFIG_DIR2, dev: isDev });
+    if (options.open) {
+      await open(`http://localhost:${port}`);
+    }
+    const shutdown = () => {
+      console.log("\nShutting down EchoSpace...");
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
   }
-  const shutdown = () => {
-    console.log("\nShutting down EchoSpace...");
-    process.exit(0);
-  };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
-});
+);
 program.command("init").description("Interactive setup for LLM provider configuration").action(runInit);
 program.parse();