docs: consolidate scattered *.md into a best-in-class docs/ set
ober
ff32d51fb670d380d219f19928892f70cc451d75
deleted file mode 100644 --- a/PLAN.md +++ /dev/null @@ -1,602 +0,0 @@ -# Jerboa-Code Implementation Plan - -*A portable AI coding agent in Chez Scheme* - -## Project Goal - -Implement a fully-featured AI coding agent equivalent to OpenCode, but: -- **Portable**: Runs on FreeBSD, Linux, macOS, Windows, anywhere Chez Scheme runs -- **Simple**: Clean architecture without JavaScript ecosystem bloat -- **Fast**: Single static binary, no runtime dependencies -- **Maintainable**: ~5,000 lines of Scheme vs 294,000 lines of TypeScript - -## Available Jerboa Standard Library - -The following modules are already available in `~/mine/jerboa/lib/std/`: - -### Core Infrastructure ✓ -- `(std net request)` - HTTP client (GET, POST, PUT, DELETE) -- `(std db sqlite)` - SQLite database with prepared statements -- `(std misc process)` - Process execution, subprocess I/O -- `(std text json)` - JSON reader/writer -- `(std os shell)` - Shell utilities -- `(std os path)` - Path manipulation -- `(std os env)` - Environment variables -- `(std os temp)` - Temporary files - -### Additional Useful Modules ✓ -- `(std text glob)` - Glob pattern matching -- `(std config)` - Configuration file parsing -- `(std cli getopt)` - Command-line argument parsing -- `(std log)` - Structured logging -- `(std misc uuid)` - UUID generation -- `(std text base64)` - Base64 encoding -- `(std crypto digest)` - Cryptographic hashing -- `(std net uri)` - URI parsing -- `(std text diff)` - Text diff/patch -- `(std misc retry)` - Retry with backoff - ---- - -## Architecture Overview - -``` -jerboa-code/ -├── lib/ -│ └── jerboa-code/ -│ ├── core/ -│ │ ├── agent.sls # Main agent loop -│ │ ├── message.sls # Message types and handling -│ │ ├── session.sls # Session persistence -│ │ └── config.sls # Configuration management -│ │ -│ ├── provider/ -│ │ ├── provider.sls # Provider abstraction -│ │ ├── openai.sls # OpenAI/compatible APIs -│ │ ├── anthropic.sls # Anthropic Claude API -│ │ ├── google.sls # Google Gemini API -│ │ └── models.sls # Model definitions -│ │ -│ ├── tool/ -│ │ ├── registry.sls # Tool registration -│ │ ├── file.sls # read, write, edit tools -│ │ ├── bash.sls # Shell command execution -│ │ ├── search.sls # grep, glob, find -│ │ ├── web.sls # HTTP fetch, web search -│ │ └── batch.sls # Parallel tool execution -│ │ -│ └── ui/ -│ ├── cli.sls # Command-line interface -│ ├── repl.sls # Interactive REPL -│ └── format.sls # Output formatting -│ -├── main.ss # Entry point -├── Makefile # Build system -├── jerboa.pkg # Package definition -└── PLAN.md # This file -``` - ---- - -## Implementation Phases - -### Phase 1: Foundation (Week 1-2) - -#### 1.1 Project Skeleton -```scheme -;; jerboa.pkg -(package jerboa-code - :package "jerboa-code" - :version "0.1.0" - :depends - ((std net) - (std db) - (std text) - (std misc) - (std os) - (std cli))) -``` - -#### 1.2 Configuration System -- [ ] Read `~/.config/jerboa-code/config.json` or `jerboa-code.json` -- [ ] API key management (env vars + config file) -- [ ] Model selection and provider configuration -- [ ] Project-local configuration support - -```scheme -;; lib/jerboa-code/core/config.sls -(library (jerboa-code core config) - (export load-config - config-api-key - config-model - config-provider) - (import (chezscheme) - (std text json) - (std os path) - (std os env))) -``` - -#### 1.3 Session Storage -- [ ] SQLite database for sessions -- [ ] Message persistence -- [ ] Session listing/resumption - -```scheme -;; lib/jerboa-code/core/session.sls -(library (jerboa-code core session) - (export session-create - session-load - session-save - session-list - session-add-message - session-get-messages) - (import (chezscheme) - (std db sqlite) - (std misc uuid))) -``` - -#### 1.4 Message Types -- [ ] User messages -- [ ] Assistant messages -- [ ] Tool calls and results -- [ ] Streaming support - -```scheme -;; lib/jerboa-code/core/message.sls -(library (jerboa-code core message) - (export make-user-message - make-assistant-message - make-tool-call - make-tool-result - message->json - json->message) - (import (chezscheme) - (std text json))) -``` - ---- - -### Phase 2: Provider Integration (Week 2-3) - -#### 2.1 Provider Abstraction -- [ ] Generic provider interface -- [ ] API key resolution -- [ ] Model capabilities - -```scheme -;; lib/jerboa-code/provider/provider.sls -(library (jerboa-code provider provider) - (export make-provider - provider-chat - provider-stream - provider-available?) - (import (chezscheme) - (std net request) - (std text json))) -``` - -#### 2.2 OpenAI Provider -- [ ] Chat completions API -- [ ] Tool calling support -- [ ] Streaming responses -- [ ] o1/o3 reasoning models - -```scheme -;; lib/jerboa-code/provider/openai.sls -(library (jerboa-code provider openai) - (export openai-chat - openai-stream - openai-models) - (import (chezscheme) - (jerboa-code provider provider) - (std net request) - (std text json))) -``` - -#### 2.3 Anthropic Provider -- [ ] Messages API -- [ ] Extended thinking -- [ ] Tool use protocol - -```scheme -;; lib/jerboa-code/provider/anthropic.sls -(library (jerboa-code provider anthropic) - (export anthropic-chat - anthropic-stream) - (import (chezscheme) - (jerboa-code provider provider) - (std net request) - (std text json))) -``` - -#### 2.4 Additional Providers -- [ ] Google Gemini -- [ ] OpenRouter (for model aggregation) -- [ ] Local models (Ollama) - ---- - -### Phase 3: Tool System (Week 3-4) - -#### 3.1 Tool Registry -- [ ] Tool definition format -- [ ] Schema generation for AI -- [ ] Tool execution dispatch - -```scheme -;; lib/jerboa-code/tool/registry.sls -(library (jerboa-code tool registry) - (export define-tool - tool-schema - tool-execute - list-tools) - (import (chezscheme) - (std text json))) -``` - -#### 3.2 File Tools -- [ ] `read` - Read file contents -- [ ] `write` - Write file contents -- [ ] `edit` - String replacement editing -- [ ] `glob` - Find files by pattern -- [ ] `grep` - Search file contents - -```scheme -;; lib/jerboa-code/tool/file.sls -(library (jerboa-code tool file) - (export tool-read - tool-write - tool-edit - tool-glob - tool-grep) - (import (chezscheme) - (std os path) - (std text glob) - (std io))) -``` - -#### 3.3 Bash Tool -- [ ] Command execution -- [ ] Timeout handling -- [ ] Output capture -- [ ] Working directory support - -```scheme -;; lib/jerboa-code/tool/bash.sls -(library (jerboa-code tool bash) - (export tool-bash - tool-bash-with-timeout) - (import (chezscheme) - (std misc process) - (std os shell))) -``` - -#### 3.4 Web Tools -- [ ] `fetch` - HTTP GET/POST -- [ ] Basic HTML parsing - -```scheme -;; lib/jerboa-code/tool/web.sls -(library (jerboa-code tool web) - (export tool-fetch - tool-web-search) - (import (chezscheme) - (std net request) - (std markup html-parser))) -``` - -#### 3.5 Batch Execution -- [ ] Parallel tool execution -- [ ] Result aggregation - ---- - -### Phase 4: Agent Core (Week 4-5) - -#### 4.1 Main Agent Loop -```scheme -;; lib/jerboa-code/core/agent.sls -(library (jerboa-code core agent) - (export agent-run - agent-step - agent-process-response) - (import (chezscheme) - (jerboa-code core session) - (jerboa-code core message) - (jerboa-code provider provider) - (jerboa-code tool registry))) - -;; Core loop pseudocode: -;; 1. Get user input -;; 2. Add to session messages -;; 3. Send to AI provider with tool schemas -;; 4. If response has tool calls: -;; a. Execute each tool -;; b. Add results to messages -;; c. Loop back to step 3 -;; 5. Return final text response -``` - -#### 4.2 Streaming Support -- [ ] Server-sent events parsing -- [ ] Incremental output display -- [ ] Tool call streaming - -#### 4.3 Error Handling -- [ ] API error recovery -- [ ] Tool execution errors -- [ ] Network retry logic - ---- - -### Phase 5: CLI Interface (Week 5-6) - -#### 5.1 Command-Line Interface -```scheme -;; lib/jerboa-code/ui/cli.sls -(library (jerboa-code ui cli) - (export cli-main - cli-run - cli-chat - cli-session) - (import (chezscheme) - (std cli getopt) - (jerboa-code core agent))) -``` - -Commands: -- `jcode` - Start interactive session -- `jcode "prompt"` - One-shot query -- `jcode --model claude-sonnet-4` - Specify model -- `jcode --provider openai` - Specify provider -- `jcode session list` - List sessions -- `jcode session resume <id>` - Resume session -- `jcode config` - Show/edit configuration - -#### 5.2 Interactive REPL -- [ ] Readline support -- [ ] History -- [ ] Multi-line input -- [ ] Slash commands (/help, /model, /clear) - -#### 5.3 Output Formatting -- [ ] Markdown rendering (terminal) -- [ ] Code block highlighting -- [ ] Diff display -- [ ] Progress indicators - ---- - -### Phase 6: Advanced Features (Week 6-8) - -#### 6.1 MCP (Model Context Protocol) -- [ ] MCP server support -- [ ] Tool discovery via MCP -- [ ] External tool integration - -#### 6.2 Git Integration -- [ ] Workspace detection -- [ ] Commit/diff tools -- [ ] Branch management - -#### 6.3 LSP Integration (Optional) -- [ ] Use existing `(std lsp)` module -- [ ] Code intelligence tools - -#### 6.4 Plugin System -- [ ] Load external tool definitions -- [ ] Custom provider support - ---- - -## Tool Specifications - -### Core Tools (Must Have) - -| Tool | Description | OpenCode Equivalent | -|------|-------------|---------------------| -| `read` | Read file contents | `ReadTool` | -| `write` | Write file contents | `WriteTool` | -| `edit` | Replace string in file | `EditTool` | -| `bash` | Execute shell command | `BashTool` | -| `glob` | Find files by pattern | `GlobTool` | -| `grep` | Search file contents | `GrepTool` | -| `fetch` | HTTP request | `WebFetchTool` | -| `batch` | Parallel execution | `BatchTool` | - -### Extended Tools (Nice to Have) - -| Tool | Description | OpenCode Equivalent | -|------|-------------|---------------------| -| `ls` | List directory | `ListTool` | -| `patch` | Apply unified diff | `ApplyPatchTool` | -| `multi-edit` | Multiple edits | `MultiEditTool` | -| `lsp` | Language server | `LspTool` | -| `search` | Code search | `CodeSearchTool` | - ---- - -## API Specifications - -### Message Format - -```scheme -;; User message -(make-message - :role "user" - :content "Read the file main.ss") - -;; Assistant message with tool call -(make-message - :role "assistant" - :content nil - :tool-calls - [(:id "call_123" - :type "function" - :function (:name "read" :arguments "{\"path\": \"main.ss\"}"))]) - -;; Tool result -(make-message - :role "tool" - :tool-call-id "call_123" - :content "(library ...)") -``` - -### Provider Interface - -```scheme -(define-interface provider - ;; Send messages, get response - (chat [messages tools] -> response) - - ;; Stream response chunks - (stream [messages tools callback] -> void) - - ;; List available models - (models [] -> model-list)) -``` - -### Tool Interface - -```scheme -(define-interface tool - ;; Tool name for AI - (name [] -> string) - - ;; JSON schema for parameters - (schema [] -> json) - - ;; Execute tool - (execute [params] -> result)) -``` - ---- - -## File Count Estimate - -| Component | Files | Lines (est) | -|-----------|-------|-------------| -| Core (agent, session, config, message) | 4 | 800 | -| Providers (openai, anthropic, google, etc) | 5 | 1000 | -| Tools (file, bash, search, web, batch) | 6 | 1200 | -| CLI/UI | 3 | 600 | -| Utilities | 2 | 400 | -| **Total** | **20** | **4000** | - ---- - -## Build System - -```makefile -# Makefile -SCHEME = scheme -JERBOA_HOME = $(HOME)/mine/jerboa -LIBDIRS = --libdirs $(JERBOA_HOME)/lib:./lib - -.PHONY: all build run test clean - -all: build - -build: - $(SCHEME) $(LIBDIRS) --compile-imported-libraries --program main.ss - -run: - $(SCHEME) $(LIBDIRS) --script main.ss - -static: - # Build single static binary - $(SCHEME) $(LIBDIRS) --compile-whole-program main.ss jcode.wpo - cc -o jcode jcode.wpo $(CHEZ_LIBS) - -test: - $(SCHEME) $(LIBDIRS) --script test/run.ss - -clean: - rm -f *.so *.wpo jcode -``` - ---- - -## Testing Strategy - -1. **Unit Tests**: Each module has corresponding test file -2. **Integration Tests**: Full agent loop with mock provider -3. **E2E Tests**: Real API calls with test prompts - -```scheme -;; test/tool-file-test.ss -(import (std test) - (jerboa-code tool file)) - -(test-suite "file tools" - (test-case "read existing file" - (let ([result (tool-read "test/fixtures/sample.txt")]) - (assert-equal? result "hello world\n"))) - - (test-case "glob finds files" - (let ([files (tool-glob "test/**/*.ss")]) - (assert (> (length files) 0))))) -``` - ---- - -## Timeline Summary - -| Week | Phase | Deliverable | -|------|-------|-------------| -| 1-2 | Foundation | Config, session, message types | -| 2-3 | Providers | OpenAI, Anthropic working | -| 3-4 | Tools | All core tools implemented | -| 4-5 | Agent | Main loop, streaming | -| 5-6 | CLI | Interactive interface | -| 6-8 | Polish | MCP, git, testing, docs | - -**Total: 6-8 weeks for complete feature parity** - ---- - -## Success Criteria - -1. **Functional**: Can have productive coding sessions equivalent to OpenCode -2. **Portable**: Runs on FreeBSD, Linux, macOS without modification -3. **Fast**: Sub-100ms startup, single static binary -4. **Simple**: Easy to understand, modify, and extend -5. **Reliable**: No SQLite locking issues, proper error handling - ---- - -## Getting Started - -```bash -# Clone and setup -cd ~/mine -mkdir jerboa-code -cd jerboa-code - -# Create initial structure -mkdir -p lib/jerboa-code/{core,provider,tool,ui} -mkdir -p test - -# Start with main.ss -cat > main.ss << 'EOF' -#!/usr/bin/env scheme --script -(import (chezscheme) - (jerboa-code core agent) - (jerboa-code ui cli)) - -(cli-main (command-line-arguments)) -EOF - -# Build and run -make run -``` - ---- - -## References - -- OpenCode source: `~/mine/opencode/packages/opencode/src/` -- Jerboa stdlib: `~/mine/jerboa/lib/std/` -- Chez Scheme: `~/mine/ChezScheme/` -- OpenAI API: https://platform.openai.com/docs/api-reference -- Anthropic API: https://docs.anthropic.com/en/api --- a/README.md +++ b/README.md @@ -1,24 +1,95 @@ # jerboa-code -A portable AI coding agent written in Jerboa Scheme (compiled by jerbuild to -Chez). Source lives under `src/jcode/`; entry point is `main.ss`. +**A portable AI coding agent written in [Jerboa](https://git.sr.ht/~lisp/jerboa) Scheme.** + +`jcode` is a terminal coding agent — think opencode / aider / Claude Code — that +compiles to a single static binary with no runtime dependencies. It talks to 13 +LLM providers (cloud and local), drives your editor through a real tool loop, +and ships a reliability layer that makes even small self-hosted models call +tools dependably. + +``` +┌────────────────────────────────────────────────────────────────┐ +│ jcode BUILD · sonnet │ +│ │ +│ › add a --json flag to the status command │ +│ │ +│ ● read src/cli.ss │ +│ ● edit src/cli.ss (+12 −1) │ +│ ● bash make test 411 passed, 0 failed │ +│ │ +│ Done — `--json` emits the status block as a JSON object. │ +└────────────────────────────────────────────────────────────────┘ +``` + +## Why it exists + +- **Portable.** One static binary. Runs on macOS, Linux (glibc + musl), FreeBSD, + and Android (via Termux). No Node, no Python, no ecosystem. +- **Provider-agnostic.** Anthropic, OpenAI, Google, OpenRouter, DeepSeek, xAI, + Groq, Mistral, Together, Cerebras, Perplexity — plus local **Ollama** and + **MLX**. Switch with `/model` mid-session. +- **Reliable on small models.** A native port of [forge](https://github.com/azambelli/forge) + plus [ATLAS](docs/FORGE.md#the-atlas-reliability-layer)-style verify-and-repair + wraps every call: prose-to-tool rescue, step enforcement, verify-gate, and + best-of-k. Always on, every provider. +- **A real TUI.** termbox-based panels, markdown + syntax highlighting, live + diffs, themes, a sidebar with token / cost / GPU stats. + +## Quickstart + +You need a built [jerboa](https://git.sr.ht/~lisp/jerboa) checkout (`JERBOA_HOME`) +and a Rust toolchain. See **[docs/getting-started.md](docs/getting-started.md)** +for the full setup. ```bash -make build # compile src/ → lib/ -make test # run test/run.ss -make binary # produce the standalone ./jcode -make run # interactive agent REPL +git clone https://git.sr.ht/~lisp/jerboa-code && cd jerboa-code + +make build # compile src/ → lib/ +make binary # produce the standalone ./jcode +./jcode keys add anthropic # store an API key (encrypted) + +./jcode # interactive REPL +./jcode --tui # full terminal UI +./jcode -p "explain this repo" # one-shot prompt ``` -## Forge guardrails +## Documentation + +| Doc | What's in it | +|---|---| +| **[Getting started](docs/getting-started.md)** | Prerequisites, building on every platform, configuration, keys, first run. | +| **[CLI reference](docs/cli.md)** | Every subcommand, flag, slash command, and environment variable. | +| **[Architecture](docs/architecture.md)** | The agent loop, module map, and how a turn flows through the guardrails. | +| **[Providers & models](docs/providers.md)** | The 13 providers, model registry, per-model sampling, and hardware tiers. | +| **[Tools](docs/tools.md)** | The agent's toolbox (file, bash, web, git, patch, task, MCP) and the safety model. | +| **[TUI](docs/tui.md)** | Layout, keybindings, themes, and the rendering features. | +| **[Forge & ATLAS reliability](docs/FORGE.md)** | Guardrails, workflows, verify-gate, best-of-k, the proxy, and the eval harness. | +| **[Remote & Android](docs/remote.md)** | `serve` / `relay` / `connect` and the thin-client architecture. | + +See **[docs/](docs/)** for the full index. + +## Build targets -jcode embeds a native port of [forge](https://github.com/azambelli/forge) — a -reliability layer that makes small / self-hosted models call tools dependably. -The guardrails (rescue, validation + retry budget, respond-forcing, per-model -sampling, compaction) are **always on for every provider**. The `/forge` -command is the control / status / ablation surface, and `jcode proxy` exposes -the same guardrails over an OpenAI-compatible HTTP endpoint. +`make build` · `test` · `run` · `run-tui` · `binary` · `install` · +`linux` · `linux-arm64` · `linux-docker` · `freebsd` · `android`. +Run `make help` for the complete list. + +## Layout + +``` +main.ss entry point +src/jcode/ + core/ agent loop, config, sessions, guardrails plumbing, ATLAS + provider/ the 13 LLM providers + per-model sampling + tool/ file, bash, web, git, patch, task, repomap, lsp + guardrails/ rescue, validator, step-enforcer, respond, error budget + proxy/ OpenAI-compatible guardrail proxy + eval/ deterministic ablation harness + ui/ cli, tui-*, serve/relay/connect + mcp/ MCP client +``` -See **[docs/FORGE.md](docs/FORGE.md)** for the command reference, the workflow -engine, the proxy, and the eval/ablation harness. Design notes and forge-source -citations are in [docs/FORGE_PORT_PLAN.md](docs/FORGE_PORT_PLAN.md). +Source is **Jerboa `.ss`**, compiled by `jerbuild` to Chez `.sls` under `lib/`. +See [`AGENTS.md`](AGENTS.md) for the language reference and [`CLAUDE.md`](CLAUDE.md) +for contributor conventions. deleted file mode 100644 --- a/android/PLAN.md +++ /dev/null @@ -1,242 +0,0 @@ -# Android Client-Server Architecture Plan - -*Replace embedded-binary APK with thin GUI client connecting to jcode serve in Termux over authenticated localhost.* - -## Problem - -The current APK embeds the jcode binary and runs it in Android's app sandbox. This sandbox blocks access to Termux's filesystem, binaries, and environment — meaning no git, no jerboa-mcp, no TypeScript compiler, no ssh-agent, no access to anything the user has installed in Termux. Every new tool requires rebundling the APK. - -## Solution - -Split into two components: - -- **jcode serve** (Termux): long-running server on localhost, full access to Termux environment -- **jcode APK** (Android): thin GUI client that connects over TCP, no embedded binary - -## Architecture - -``` -┌─────────────────────────────────┐ -│ Android APK │ -│ ┌───────────┐ ┌─────────────┐ │ -│ │ MainActivity│ │SettingsActivity│ -│ │ Chat UI │ │ Host/Port │ │ -│ │ Build/Plan │ │ Auth Token │ │ -│ └──────┬──────┘ └─────────────┘ │ -│ │ │ -│ JcodeClient.kt │ -│ (Socket to 127.0.0.1:PORT) │ -│ JSONL over TCP │ -└─────────┬───────────────────────┘ - │ localhost only -┌─────────┴───────────────────────┐ -│ Termux: jcode serve │ -│ │ -│ TCP listener (127.0.0.1:PORT) │ -│ Token-based auth │ -│ Same JSONL protocol as today │ -│ │ -│ Full Termux environment: │ -│ ├── git, ssh-agent │ -│ ├── scheme (Chez), jerboa-mcp │ -│ ├── node, tsc │ -│ ├── python, cargo, etc. │ -│ └── all user-installed tools │ -└─────────────────────────────────┘ -``` - -## Security - -### Threat Model - -Other apps on the same Android device can connect to localhost ports. The jcode server must reject unauthorized connections. - -### Mitigations - -1. **Bind 127.0.0.1 only** — not reachable from the network, only from apps on this device. - -2. **Pre-shared bearer token** — on first run, `jcode serve` generates a cryptographically random 256-bit token (hex-encoded, 64 chars) and writes it to `~/.jcode/server-token`. The user enters this token once in the Android app's Settings screen. - -3. **Auth handshake** — the first message from any TCP client must be `{"type":"auth","token":"<token>"}`. The server validates it against the stored token. On mismatch: log a warning, send `{"type":"error","message":"auth failed"}`, close the socket. No further communication occurs. - -4. **Single-client mode** — the server accepts one authenticated client at a time. A second connection attempt while a client is active is rejected. This prevents session hijacking if another app somehow obtains the token. - -5. **Token rotation** — `jcode serve --rotate-token` generates a new token and prints it. The old token is immediately invalidated. - -### What This Does NOT Protect Against - -- A rooted device or debuggable app that can read `~/.jcode/server-token` -- A malicious app that has already compromised Termux's uid -- These are out of scope — if Termux is compromised, the attacker already has the user's SSH keys, API keys, and full filesystem access. - -## Server Component (Scheme) - -### Changes to `src/jcode/ui/serve.ss` - -Currently `serve-main` reads/writes stdio. Add a `--port PORT` flag: - -- Without `--port`: behave as today (stdio mode, for embedded APK backward compat) -- With `--port PORT`: open a TCP listener on `127.0.0.1:PORT` - - On connection: read first message, validate auth token - - After auth: enter the same JSONL event loop as stdio mode - - On disconnect: return to listening state (accept next client) - - On SIGTERM/SIGINT: clean shutdown - -### Token Management - -- On first run with `--port`, if `~/.jcode/server-token` does not exist, generate one and print it to stderr for the user to copy. -- Read token from `~/.jcode/server-token` (one line, hex string, no newline). -- `--rotate-token` flag: overwrite file with new random token, print to stderr, exit. - -### Protocol Changes - -The JSONL protocol is unchanged except for the initial auth handshake: - -``` -Client → Server: {"type":"auth","token":"a1b2c3..."} -Server → Client: {"type":"auth_ok"} (on success) -Server → Client: {"type":"error","message":"auth failed"} (on failure, then close) - -... then normal JSONL protocol as today: -Client → Server: {"type":"user","text":"...","mode":"build"} -Server → Client: {"type":"ready","session_id":"...","session_title":"..."} -Server → Client: {"type":"token","text":"..."} -... -``` - -### Startup - -Typical Termux workflow: - -``` -$ jcode serve --port 8321 -[INFO] token: a1b2c3d4... (copy this to the Android app) -[INFO] listening on 127.0.0.1:8321 -[INFO] waiting for client... -``` - -On subsequent runs the token is reused silently (no reprint unless `--show-token`). - -## APK Component (Kotlin) - -### JcodeClient.kt (replaces JcodeProcess.kt) - -Replace `ProcessBuilder`-based subprocess management with TCP socket connection: - -- Connect to `host:port` (default `127.0.0.1:8321`, configurable in Settings) -- Send auth message with stored token -- Wait for `auth_ok` response -- Enter same JSONL read/write loop as current `JcodeProcess` reader/writer threads -- On socket disconnect: show "Disconnected — is jcode serve running in Termux?" with a Reconnect button -- Reconnect with exponential backoff (1s, 2s, 4s, max 10s) - -### SettingsActivity.kt Changes - -Add fields: -- **Server host** — text input, default `127.0.0.1` -- **Server port** — number input, default `8321` -- **Auth token** — text input (paste the 64-char hex token from Termux) -- **Connection status** — indicator (connected/disconnected/auth failed) - -Remove: -- The jcode.json / API key picker (keys are now on the server side in Termux's jcode.json) - -### MainActivity.kt Changes - -- On launch: attempt to connect to configured host:port -- Show connection state in the toolbar (green dot = connected, red = disconnected) -- If not connected: show a banner with instructions ("Start jcode serve in Termux") -- Remove all JcodeProcess subprocess logic - -### APK Build Changes (build-apk.sh) - -Remove from the build: -- jcode binary bundling (`libjcode.so`) -- `chez_sqlite_shim.so` bundling -- Termux shared lib staging (`assets/native/`, libncursesw, libiconv, libsqlite3, libz) -- The binary verification step (`file` check for ARM aarch64) -- The `JCODE_BINARY` variable and its existence check - -The APK becomes pure Kotlin — no native code, no `extractNativeLibs`. Expected size: well under 1MB. - -### Manifest Changes - -- Remove `android:extractNativeLibs="true"` (no native libs) -- Keep `android:debuggable="true"` for dev builds (remove before any real distribution) -- Keep INTERNET permission (needed for localhost socket) - -## Implementation Order - -### Phase 1: Server-side TCP listener -1. Add `--port PORT` flag parsing to `serve-main` -2. Implement TCP listener with `(std net tcp)` or raw Chez `tcp-connect`/`tcp-listen` -3. Implement token generation, storage, and validation -4. Auth handshake: validate first message, send `auth_ok` or reject -5. After auth: reuse existing `serve-loop` with TCP streams instead of stdio -6. Test from Termux: `echo '{"type":"auth","token":"..."}' | nc 127.0.0.1 8321` - -### Phase 2: APK client refactor -1. Write `JcodeClient.kt` — Socket-based JSONL with auth handshake -2. Update `SettingsActivity.kt` — host/port/token fields, remove key picker -3. Update `MainActivity.kt` — connection state UI, remove subprocess logic -4. Strip `build-apk.sh` — remove all native binary/lib bundling -5. Build, install via `adb install`, test against Phase 1 server - -### Phase 3: Polish -1. Auto-reconnect on disconnect with backoff -2. Connection status indicator in toolbar -3. "Server not running" banner with clear instructions -4. `jcode serve --background` or Termux:Boot integration for auto-start -5. Optional: mDNS/zeroconf discovery so the app finds the server without manual port config - -## MCP Integration - -With jcode serve running in Termux, jerboa-mcp (and any other MCP server) works exactly as it does on desktop: - -```json -// In Termux's ~/.jcode/config.json or jcode.json: -{ - "mcpServers": { - "jerboa": { - "command": "scheme", - "args": ["--libdirs", "/path/to/jerboa-mcp/lib", "--script", "/path/to/jerboa-mcp/main.ss"] - } - } -} -``` - -jcode serve spawns the MCP server as a stdio subprocess (existing `init-mcp-tools` code), registers its tools, and they appear in the LLM's tool list. The Android app doesn't need to know or care — it just renders tool call events like any other. - -## Git / SSH Integration - -With jcode serve running in Termux: - -- `git` is in PATH — jcode's bash tool can clone, pull, push, branch, etc. -- If the user has `ssh-agent` running and keys loaded (`ssh-add`), git SSH operations just work — jcode serve inherits `SSH_AUTH_SOCK` from the Termux environment. -- Working directory for agent sessions is any Termux-accessible path, not the sandboxed app dir. - -Typical user flow: -1. In Termux: `eval $(ssh-agent) && ssh-add ~/.ssh/id_ed25519` -2. In Termux: `cd ~/projects && jcode serve --port 8321` -3. Open jcode app: "Clone https://github.com/user/repo into ~/projects/repo" -4. jcode runs `git clone ...` via bash tool — works because git and SSH are available. - -## File Sizes (estimated) - -| Component | Before | After | -|-----------|--------|-------| -| APK | 16 MB | < 1 MB | -| Termux server | (embedded) | 0 (already installed as `jcode` binary) | -| Total on device | 16 MB | < 1 MB + existing jcode | - -## Open Questions - -1. **Multiple clients** — should the server support multiple simultaneous APK connections (e.g., tablet + phone)? Current plan says no (single-client). Could revisit. - -2. **Session persistence** — sessions are stored in Termux's SQLite DB. The app is stateless. Is this fine, or should the app cache recent messages for offline viewing? - -3. **Notifications** — should the APK show a notification when a long-running agent turn completes while the app is backgrounded? Requires a foreground service. - -4. **Auto-start** — should we provide a Termux:Boot script to auto-start `jcode serve` on device boot? - -5. **TLS** — localhost doesn't need encryption (no network exposure), but adding TLS with a self-signed cert would prevent other local apps from even seeing the traffic via packet capture. Low priority. deleted file mode 100644 --- a/claude-api-skill.md +++ /dev/null @@ -1,1299 +0,0 @@ -# Claude API Skill — Comprehensive Reference - -This document is a comprehensive reference for building LLM-powered applications with Claude, derived from the `claude-api` skill bundled with Claude Code. - ---- - -## Table of Contents - -1. [Overview & Output Requirements](#overview--output-requirements) -2. [Defaults](#defaults) -3. [Subcommands](#subcommands) -4. [Language Detection](#language-detection) -5. [Which Surface Should I Use?](#which-surface-should-i-use) -6. [Architecture](#architecture) -7. [Current Models](#current-models) -8. [Thinking & Effort](#thinking--effort) -9. [Compaction](#compaction) -10. [Prompt Caching](#prompt-caching) -11. [Python SDK Reference](#python-sdk-reference) -12. [TypeScript SDK Reference](#typescript-sdk-reference) -13. [Tool Use](#tool-use) -14. [Managed Agents](#managed-agents) -15. [Batches API](#batches-api) -16. [Files API](#files-api) -17. [Streaming](#streaming) -18. [Structured Outputs](#structured-outputs) -19. [Model Migration](#model-migration) -20. [Error Handling](#error-handling) -21. [Cloud Providers](#cloud-providers) -22. [Live Sources](#live-sources) - ---- - -## Overview & Output Requirements - -### Before You Start