ever-terminal 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xiang Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# Ever Terminal
+
+`ever-terminal` is designed to be used with the Even App.
+
+> Building glasses-native apps instead of mirroring your laptop? See [@evenrealities/even_hub_sdk](https://www.npmjs.com/package/@evenrealities/even_hub_sdk).
+
+Supports macOS, Linux, Windows.
+
+---
+
+## Requirements
+
+- **Node.js 18+** — check with `node --version`. Install from [nodejs.org](https://nodejs.org), or `brew install node` (macOS), or your distro's package manager (Linux).
+- An **Even Realities G2** + **R1 ring**, paired through the Even app (iOS/Android).
+- Optional but recommended: a [Tailscale](https://tailscale.com) account signed in on both your laptop and phone — gives you a stable private network without needing the public-tunnel providers below.
+
+---
+
+## Install
+
+```bash
+npm install -g ever-terminal
+```
+
+Verify the install:
+
+```bash
+ever-terminal --version
+```
+
+Update to the latest release:
+
+```bash
+npm install -g ever-terminal@latest
+```
+
+---
+
+## Quick Start
+
+```bash
+ever-terminal
+```
+
+By default the server starts on `http://localhost:3456`.
+
+Useful startup options:
+
+```bash
+ever-terminal --cwd /path/to/project
+ever-terminal --port 8080
+ever-terminal --token mytoken123
+ever-terminal --name my-laptop
+ever-terminal --provider codex
+ever-terminal --expose pinggy
+ever-terminal --expose bore
+ever-terminal --expose ngrok
+```
+
+---
+
+## How it works
+
+ever-terminal runs a local HTTP server on `:3456` (configurable via `--port`), spawns your AI agent (Claude Code or Codex) as a child process, captures its streaming output, renders it onto the G2's 576×288 canvas, and translates R1 ring gestures back into keyboard events for the agent.
+
+The Even app connects to your laptop over your chosen transport. By default it binds to your detected LAN address (same Wi-Fi). Pass `--tailscale` to bind on your Tailscale tailnet instead (stable across networks, end-to-end WireGuard), `-i <interface>` to pin a specific network interface, or `--expose pinggy` / `--expose bore` / `--expose ngrok` to open a temporary public tunnel.
+
+```
+                       ┌──────────────────┐
+                       │   your laptop    │
+   [ claude / codex ] ─│   ever-terminal  │
+                       │   :3456          │
+                       └────────┬─────────┘
+                                │
+                ┌───────────────┴───────────────┐
+                │   transport (pick one)        │
+                │   default: LAN (same Wi-Fi)   │
+                │   --tailscale                 │
+                │   --expose pinggy             │
+                │   --expose bore               │
+                │   --expose ngrok              │
+                └───────────────┬───────────────┘
+                                │
+                       ┌────────┴─────────┐
+                       │     Even app     │
+                       └──┬────────────┬──┘
+                       (display)     (input)
+                       BLE ↓          ↑ BLE
+                     ┌────┴────┐  ┌────┴────┐
+                     │   G2    │  │   R1    │
+                     │ 576×288 │  │  ring   │
+                     └─────────┘  └─────────┘
+```
+
+The agent is *your* binary running on *your* laptop. ever-terminal is a renderer + input bridge, not a runtime.
+
+---
+
+## CLI
+
+```text
+ever-terminal [command] [options]
+
+Commands:
+  ever-terminal start
+  ever-terminal complete <shell>
+
+Local network options:
+  --tailscale
+  -i, --interface, --if <name>
+
+Quick public expose options:
+  --expose <provider>   Quick public expose provider (`pinggy`, `bore`, `ngrok`)
+
+Options:
+  -p, --port <n>
+  -t, --token <str>
+  -n, --name <str>
+  -d, --cwd <path>
+  --provider <name>   claude, codex (default: claude)
+  --log-file [path]
+  --verbose
+  -h, --help
+  -v, --version
+
+Examples:
+  ever-terminal
+  ever-terminal -p 8080
+  ever-terminal -t mytoken123
+  ever-terminal --expose pinggy
+  ever-terminal --expose ngrok
+```
+
+Quick public expose helpers are intended for simple temporary sharing, not long-term use.
+For stable setups, prefer a proper network path such as Tailscale or a production tunnel configuration.
+
+Current quick expose providers:
+
+### pinggy
+
+No install required — uses your system's SSH client. Just pass `--expose pinggy`.
+
+Behind the scenes:
+
+```bash
+ssh -p 443 -R0:localhost:<port> a.pinggy.io
+```
+
+Pinggy is a hosted SSH-tunnel service; the public URL appears in your terminal once the tunnel is up.
+
+### bore
+
+Self-hostable, written in Rust. GitHub: [ekzhang/bore](https://github.com/ekzhang/bore).
+
+Install:
+
+- **macOS:** `brew install bore-cli` *(or)* `cargo install bore-cli`
+- **Linux:** `cargo install bore-cli` *(or)* download a prebuilt binary from [releases](https://github.com/ekzhang/bore/releases) and put `bore` on your `$PATH`
+- **Windows:** download `bore-vX.Y.Z-x86_64-pc-windows-msvc.zip` from [releases](https://github.com/ekzhang/bore/releases), extract `bore.exe`, add its folder to your `PATH`
+
+Verify with `bore --version`. Then `--expose bore` runs:
+
+```bash
+bore local <port> --to bore.pub
+```
+
+### ngrok
+
+Hosted tunnel service, free tier available. Site: [ngrok.com](https://ngrok.com).
+
+Install:
+
+- **macOS:** `brew install ngrok/ngrok/ngrok`
+- **Linux:** see the apt/yum repos at [ngrok.com/download](https://ngrok.com/download) — or download the tarball, extract, and put `ngrok` on your `$PATH`
+- **Windows:** download the zip from [ngrok.com/download](https://ngrok.com/download), extract `ngrok.exe`, add its folder to your `PATH`
+
+One-time setup — sign up at [ngrok.com](https://ngrok.com), copy your authtoken from the dashboard, then:
+
+```bash
+ngrok config add-authtoken <your-token>
+```
+
+Verify with `ngrok --version`. Then `--expose ngrok` runs:
+
+```bash
+ngrok http <port>
+```
+
+Shell completion (example usage):
+
+```text
+ever-terminal complete zsh
+ever-terminal complete bash
+ever-terminal complete fish
+ever-terminal complete powershell
+```
+
+Each form prints the completion script for that shell.
+
+
+## Flow
+
+1. Start the server with `ever-terminal`. It prints a connection URL, a token, and a QR code in the terminal.
+2. Open the Even app on your phone and scan the QR code — or paste the URL and token manually if scanning isn't convenient.
+3. Your G2 glasses and R1 ring connect via BLE through the Even app. The agent's output streams onto the glasses, and ring gestures route back to the agent as keyboard events.
+
+
+## Providers
+
+The server can drive all supported providers concurrently; `--provider <name>`
+just chooses the **default**. Each provider wraps its own CLI — make sure the
+binary is installed and authenticated beforehand.
+
+| Provider   | Required CLI    | Auth                           | Override path env  |
+|------------|-----------------|--------------------------------|--------------------|
+| `claude`   | `claude`        | `claude login` (Claude Code)   | n/a                |
+| `codex`    | `codex`         | `codex` first-run wizard       | n/a                |
+
+---
+
+## Common problems
+
+| **Symptom**                                               | **Cause**                                               | **Fix**                                                                                  |
+|-----------------------------------------------------------|---------------------------------------------------------|------------------------------------------------------------------------------------------|
+| Phone app shows "Server unreachable"                      | Laptop and phone on different transports                | Match: both on Tailscale (`--tailscale`) or both on the same Wi-Fi                       |
+| `EADDRINUSE :3456`                                        | Another ever-terminal already running                   | `lsof -i :3456` → kill old one, or pass `--port <other>`                                 |
+| `command not found: claude` or `codex`                   | Agent binary not on `$PATH`                             | Install per the Providers table; verify with `which claude` / `which codex`              |
+| `--expose pinggy` hangs                                   | Pinggy edge timing out                                  | Switch to `--expose bore`, `--expose ngrok`, or Tailscale                                |
+| Token rotates every restart                               | Not passing `--token`                                   | `ever-terminal --token my-fixed-token`                                                   |
+| Output truncated mid-stream                               | Agent printed something the 576×288 layout can't render | Re-run with `--verbose --log-file ./debug.log` and open an issue with the offending line |
+
+For anything else: `ever-terminal --verbose --log-file ./debug.log`, reproduce, attach the log to an email to software@evenrealities.com .
+
+---
+
+## Changelog
+
+### 0.8.1
+
+- optimize codex session history performance for large session (windows)
+- add `--expose ngrok` support (need to sign in elsewhere first)
+
+### 0.8.0
+
+- codex now only starts a background process when necessary
+
+### 0.7.9
+
+- add debug timing for codex history api
+- fix middle deny behavior in multiple permission requests
+
+### 0.7.8
+
+- add update check api
+
+### 0.7.7
+
+- improve codex support with `ever-terminal codex` wrapper which can sync
+messages between codex cli and glasses
+- internal refactoring
+
+---
+
+## License
+
+MIT

package/dist/claude/provider.js

@@ -0,0 +1,234 @@
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { listSessions, getSessionMessages, } from "@anthropic-ai/claude-agent-sdk";
+import { ClaudeSession } from "./session.js";
+/** Find the jsonl file for a Claude session by scanning project dirs. */
+function findSessionFile(sessionId) {
+    const claudeDir = join(homedir(), ".claude", "projects");
+    if (!existsSync(claudeDir))
+        return null;
+    for (const dir of readdirSync(claudeDir)) {
+        const p = join(claudeDir, dir, `${sessionId}.jsonl`);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/** Read last line of a jsonl file. */
+function readLastLine(filePath) {
+    try {
+        const data = readFileSync(filePath, "utf8");
+        const lines = data.trimEnd().split("\n");
+        if (lines.length === 0)
+            return null;
+        return JSON.parse(lines[lines.length - 1]);
+    }
+    catch {
+        return null;
+    }
+}
+/** Determine session status by reading the jsonl file directly. */
+export function claudeSessionStatus(sessionId) {
+    const file = findSessionFile(sessionId);
+    if (!file)
+        return "idle";
+    const last = readLastLine(file);
+    if (!last)
+        return "idle";
+    if (last.type === "last-prompt")
+        return "idle";
+    if (last.type === "system" &&
+        (last.subtype === "stop_hook_summary" || last.subtype === "turn_duration"))
+        return "idle";
+    if (last.type === "assistant" &&
+        last.message?.stop_reason &&
+        last.message.stop_reason !== "tool_use")
+        return "idle";
+    if (last.type === "result")
+        return "idle";
+    if (last.type === "permission-mode")
+        return "idle";
+    if (last.type === "user") {
+        const c = last.message?.content;
+        const text = typeof c === "string" ? c : c?.[0]?.text ?? "";
+        if (text.includes("Request interrupted by user"))
+            return "idle";
+    }
+    if (last.timestamp) {
+        const ageMs = Date.now() - new Date(last.timestamp).getTime();
+        if (ageMs > 120_000)
+            return "idle";
+    }
+    return "busy";
+}
+// ── Provider factory ────────────────────────────────────
+export function createClaudeProvider(emit) {
+    const sessions = new Map();
+    function makeSession(sessionId) {
+        if (sessionId) {
+            const existing = sessions.get(sessionId);
+            if (existing)
+                return existing;
+        }
+        const session = new ClaudeSession(emit);
+        session.onIdReady((sid) => {
+            if (!sessions.has(sid))
+                sessions.set(sid, session);
+        });
+        if (sessionId)
+            sessions.set(sessionId, session);
+        return session;
+    }
+    async function prompt(sessionId, text, cwd) {
+        let session;
+        if (sessionId)
+            session = sessions.get(sessionId);
+        if (sessionId && !session && !findSessionFile(sessionId)) {
+            throw Object.assign(new Error(`Claude session not found: ${sessionId}`), { statusCode: 404 });
+        }
+        if (!session) {
+            session = makeSession(sessionId);
+            await session.start(sessionId, cwd);
+        }
+        // Emit user_prompt when session ID is known
+        session.onIdReady((sid) => {
+            emit(sid, { type: "user_prompt", text });
+        });
+        if (session.busy) {
+            session.enqueue(text);
+        }
+        else {
+            session.run(text).catch((err) => {
+                console.error(`[claude-provider] run failed: ${err.message}`);
+            });
+        }
+        const resolvedId = session.id ??
+            (await session.waitForId(10000).catch(() => null)) ??
+            "";
+        return { sessionId: resolvedId, provider: "claude" };
+    }
+    function respondPermission(sessionId, decision) {
+        sessions.get(sessionId)?.respondPermission(decision);
+    }
+    function respondQuestion(sessionId, answer) {
+        sessions.get(sessionId)?.respondQuestion(answer);
+    }
+    function interrupt(sessionId) {
+        sessions.get(sessionId)?.interrupt();
+    }
+    function getStatus(sessionId) {
+        const session = sessions.get(sessionId);
+        if (!session)
+            return null;
+        return { state: session.status, provider: "claude" };
+    }
+    async function getSessionStatus(sessionId) {
+        const session = sessions.get(sessionId);
+        if (session)
+            return session.status;
+        return claudeSessionStatus(sessionId);
+    }
+    async function listClaudeSessions(limit, cwd) {
+        const infos = await listSessions(cwd ? { dir: cwd, limit } : { limit });
+        return infos.map((info) => ({
+            id: info.sessionId,
+            title: (info.customTitle ||
+                info.summary ||
+                info.firstPrompt ||
+                "").slice(0, 64),
+            timestamp: new Date(info.lastModified).toISOString(),
+            cwd: info.cwd || "",
+            provider: "claude",
+            status: null,
+        }));
+    }
+    async function getInfo() {
+        const { exec } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execAsync = promisify(exec);
+        let version = "";
+        try {
+            const { stdout } = await execAsync("claude --version", {
+                timeout: 3000,
+            });
+            version = stdout.trim().replace(" (Claude Code)", "");
+        }
+        catch { }
+        let account = {};
+        let model = "";
+        try {
+            const recent = await listSessions({ limit: 3 });
+            for (const info of recent) {
+                const messages = await getSessionMessages(info.sessionId);
+                for (let i = messages.length - 1; i >= 0; i--) {
+                    const entry = messages[i];
+                    if (entry.type !== "assistant")
+                        continue;
+                    const m = entry.message?.model;
+                    if (m) {
+                        model = m;
+                        break;
+                    }
+                }
+                if (model)
+                    break;
+            }
+        }
+        catch { }
+        let modelDisplay = "";
+        if (model) {
+            const parts = model
+                .replace("claude-", "")
+                .replace(/-\d{8,}$/, "")
+                .split("-");
+            const name = parts[0].charAt(0).toUpperCase() + parts[0].slice(1);
+            const ver = parts.slice(1).join(".");
+            modelDisplay = name + (ver ? " " + ver : "");
+        }
+        try {
+            const { stdout } = await execAsync("claude auth status", {
+                timeout: 5000,
+            });
+            const auth = JSON.parse(stdout.trim());
+            account = {
+                email: auth.email ?? "",
+                organization: auth.orgName ?? "",
+                subscriptionType: auth.subscriptionType ?? "",
+            };
+        }
+        catch { }
+        return {
+            account,
+            model: modelDisplay || "Unknown",
+            version: version || "Unknown",
+            provider: "claude",
+        };
+    }
+    const MAX_HISTORY_ITEMS = 10;
+    async function getHistory(sessionId, limit) {
+        const messages = await getSessionMessages(sessionId);
+        const reduced = messages.reduce(function (acc, msg) {
+            const contents = msg.message?.content;
+            for (const content of contents) {
+                if (content?.type === "text") {
+                    acc.push({ role: msg.type, text: content.text });
+                }
+            }
+            return acc;
+        }, []);
+        const returnCount = Math.min(limit, MAX_HISTORY_ITEMS);
+        return reduced.slice(-returnCount);
+    }
+    return {
+        listSessions: listClaudeSessions,
+        getSessionStatus,
+        getInfo,
+        getHistory,
+        prompt,
+        respondPermission,
+        respondQuestion,
+        interrupt,
+        getStatus,
+    };
+}