openpoly 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 polycode contributors
+
+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,156 @@
+# polycode
+
+An open-source, model-agnostic terminal coding agent — like Claude Code, but with **free, open-source models**. Use DeepSeek, GLM, Qwen, Llama and more via [OpenRouter](https://openrouter.ai)'s free tier, run them locally with [Ollama](https://ollama.com), or bring your own GPT/Claude/Gemini keys — all from one terminal UI.
+
+```
+›  add input validation to the signup form
+
+● read   src/auth/signup.ts
+● edit   src/auth/signup.ts
+● run    npm test
+I added validation and the tests pass.
+```
+
+## Features
+
+- **Free, open-source models.** Use DeepSeek, GLM, Qwen, Llama, gpt-oss and more for free via [OpenRouter](https://openrouter.ai)'s free tier — one free API key, **no credit card**.
+- **Fully local & keyless option.** Run open models on your own machine with [Ollama](https://ollama.com) — no key, no limits.
+- **Any model.** Built on the [Vercel AI SDK](https://sdk.vercel.ai) — also works directly with OpenAI, Anthropic, Google, and any OpenAI-compatible endpoint using your own keys.
+- **In-terminal model picker.** Run `/model` for a Claude-Code-style menu pre-loaded with the live list of all tool-capable models (250+) — free ones marked `·free` and listed first; type to filter, arrow keys to select.
+- **Real coding tools.** Read, write, and edit files; run shell commands; search the codebase.
+- **Permission prompts.** Approve each file write and command (`y` / `a` always / `n` deny), or run with `--yolo` to auto-approve.
+- **Rich terminal UI** built with [Ink](https://github.com/vadimdemedes/ink): streaming output, colored diffs, live tool status.
+- **Switch models on the fly** with `/model <name>` — your conversation is kept.
+- **Adjustable thinking speed.** Reasoning models can be slow; `/think off|low|medium|high` dials reasoning effort (default `low` for speed). Press **Esc** to cancel a slow turn.
+
+## Install
+
+### One command (anyone, anywhere)
+
+```bash
+npm install -g openpoly
+```
+
+That's it — no cloning, no folders. Now open **any** terminal, `cd` into a project, and run `polycode` (or `openpoly`). It works on whatever directory you're in. Update with `npm i -g openpoly@latest`; remove with `npm rm -g openpoly`.
+
+### Install from source (for development)
+
+```bash
+# from anywhere — point npm at the project folder; it builds and installs globally
+npm install -g /absolute/path/to/polycode
+```
+
+```powershell
+# Windows PowerShell
+npm install -g "C:\path\to\polycode"
+```
+
+Now open **any** terminal, `cd` into a project you want help with, and run:
+
+```bash
+polycode
+```
+
+To update later, re-run the install command. To remove it: `npm rm -g polycode`.
+
+### Run from source (no global install)
+
+```bash
+cd polycode
+npm install
+npm run dev
+```
+
+## Configure
+
+### Recommended: free models via OpenRouter
+
+1. Create a **free** OpenRouter API key (no credit card) at [openrouter.ai/keys](https://openrouter.ai/keys).
+2. Run `polycode`. On first run it **prompts you to paste the key right in the terminal** (masked) and saves it for next time — no env-var setup needed. Type `/key` anytime to enter or change it.
+3. The default model is `gpt-oss` (OpenAI gpt-oss-120b, free). Run **`/model`** (or `/models`) to open a picker populated with **all 250+ tool-capable models** — free ones marked `·free` and shown first; type to filter, arrow keys to move, enter to select. The free set rotates; DeepSeek/GLM/Kimi show up whenever they're offered free.
+
+> Prefer env vars? Set `OPENROUTER_API_KEY` (PowerShell: `$env:OPENROUTER_API_KEY="sk-or-..."`) and the prompt is skipped. The terminal-entered key is stored at `~/.config/polycode/auth.json`.
+
+> Free models are rate-limited (≈20 requests/min, ≈200/day) and shared, so they can be slower or briefly unavailable.
+
+### Fully local & free with Ollama (no key)
+
+Install [Ollama](https://ollama.com), pull a model, then pick a `*-local` model:
+
+```bash
+ollama pull qwen3        # or: ollama pull deepseek-r1 / glm4
+polycode --model=qwen-local
+```
+
+No API key, no rate limits — it runs on your machine.
+
+### Config file
+
+On first run, polycode seeds `~/.config/polycode/config.json` (older configs are auto-migrated; the previous file is kept as `config.json.bak`):
+
+```json
+{
+  "version": 2,
+  "defaultModel": "qwen-coder",
+  "models": [
+    { "name": "qwen-coder", "provider": "openrouter", "model": "qwen/qwen3-coder:free" },
+    { "name": "llama", "provider": "openrouter", "model": "meta-llama/llama-3.3-70b-instruct:free" },
+    { "name": "gpt-oss", "provider": "openrouter", "model": "openai/gpt-oss-120b:free" },
+    { "name": "deepseek-local", "provider": "openai-compatible", "model": "deepseek-r1", "baseURL": "http://localhost:11434/v1" },
+    { "name": "claude-direct", "provider": "anthropic", "model": "claude-3-5-sonnet-latest" }
+  ]
+}
+```
+
+With `OPENROUTER_API_KEY` set you can also `/model <any-openrouter-id>` directly without editing config (e.g. `/model deepseek/deepseek-chat-v3.1:free`).
+
+### API keys (env vars, never written to disk)
+
+| Provider            | Env var                          |
+| ------------------- | -------------------------------- |
+| `openrouter`        | `OPENROUTER_API_KEY` (free at openrouter.ai/keys) |
+| `openai-compatible` | none for local Ollama/LM Studio  |
+| `openai`            | `OPENAI_API_KEY`                 |
+| `anthropic`         | `ANTHROPIC_API_KEY`              |
+| `google`            | `GOOGLE_GENERATIVE_AI_API_KEY`   |
+
+You can also drop a project-level `.polycode.json` in any repo to override or add models for that project.
+
+## Usage
+
+```bash
+polycode                      # start with the default model
+polycode --model=llama        # start with a specific model
+polycode --yolo               # auto-approve writes and commands
+```
+
+In-session commands:
+
+| Command         | Description                                      |
+| --------------- | ------------------------------------------------ |
+| `/think <lvl>`  | reasoning effort: `off`/`low`/`medium`/`high` (lower = faster) |
+| `/key`          | enter/update the API key for the current model   |
+| `/model`        | open the picker — free models, type to filter    |
+| `/models`       | same as `/model`                                 |
+| `/model <name>` | switch directly (any OpenRouter model id works)  |
+| `/clear`        | clear the conversation                           |
+| `/help`         | show help                                        |
+| `/exit`         | quit                                             |
+
+## Architecture
+
+```
+src/
+  cli.tsx            entry point — args, wiring, render
+  config/            load/merge config (versioned, auto-migrating), resolve keys
+  providers/         map a config entry → a Vercel AI SDK model; list free models
+  tools/             read / write / edit / run_command / search_code + permission broker
+  agent/             the agentic loop (streamText + tools, multi-step)
+  tui/               Ink components — transcript, permission dialog, status bar
+```
+
+The agent loop leans on the Vercel AI SDK's multi-step tool calling so behavior is uniform across providers. Tools request approval through a `PermissionBroker` that bridges tool execution and the UI.
+
+## License
+
+MIT

package/dist/agent/agent.js

@@ -0,0 +1,233 @@
+import { EventEmitter } from "node:events";
+import { streamText, generateText, } from "ai";
+import { buildSystemPrompt } from "./systemPrompt.js";
+/**
+ * Owns the conversation state and drives one agentic turn per `send()`.
+ * Relies on the Vercel AI SDK's multi-step loop (maxSteps) to handle the
+ * model<->tool round-trips uniformly across providers. Emits streaming events
+ * the TUI subscribes to.
+ */
+export class AgentSession extends EventEmitter {
+    model;
+    tools;
+    messages = [];
+    system;
+    busy = false;
+    controller = null;
+    // Default to "low" so reasoning models stay snappy; raise with /think.
+    reasoning = "low";
+    constructor(model, tools, cwd) {
+        super();
+        this.model = model;
+        this.tools = tools;
+        this.system = buildSystemPrompt(cwd);
+    }
+    /** Swap the underlying model mid-session (used by /model). History is kept. */
+    setModel(model) {
+        this.model = model;
+    }
+    hasModel() {
+        return this.model !== null;
+    }
+    /** Drop conversation history (used by /clear). */
+    clearHistory() {
+        this.messages = [];
+    }
+    isBusy() {
+        return this.busy;
+    }
+    setReasoning(level) {
+        this.reasoning = level;
+    }
+    getReasoning() {
+        return this.reasoning;
+    }
+    /**
+     * OpenRouter reasoning control, passed through the openai-compatible provider
+     * (it spreads providerOptions["openrouter"] into the request body). Lower
+     * effort = less "thinking" = faster. Ignored by non-OpenRouter providers.
+     */
+    reasoningOptions() {
+        const reasoning = this.reasoning === "off"
+            ? { enabled: false }
+            : { effort: this.reasoning };
+        return { openrouter: { reasoning } };
+    }
+    /** Cancel the in-flight turn, if any (Esc). Triggers the stream to abort. */
+    abort() {
+        this.controller?.abort();
+    }
+    /** Emit an error, but report a user-initiated abort gently instead. */
+    emitError(err) {
+        if (this.controller?.signal.aborted)
+            this.emit("error", "⊘ Cancelled.");
+        else
+            this.emit("error", describeError(err));
+    }
+    async send(userText) {
+        if (this.busy)
+            return;
+        if (!this.model) {
+            this.emit("error", "No model configured. Use /model <name> to pick one, or set the provider's API key and restart.");
+            this.emit("done");
+            return;
+        }
+        this.busy = true;
+        this.controller = new AbortController();
+        this.messages.push({ role: "user", content: userText });
+        try {
+            const result = streamText({
+                model: this.model,
+                system: this.system,
+                messages: this.messages,
+                tools: this.tools,
+                maxSteps: 30,
+                // Free model endpoints are often briefly rate-limited (HTTP 429 with a
+                // short retry-after); a few extra backoff retries ride most of them out.
+                maxRetries: 4,
+                abortSignal: this.controller.signal,
+                providerOptions: this.reasoningOptions(),
+                // Weaker free models sometimes emit malformed tool calls (e.g. a
+                // write_file with no "path"). Re-ask the model to redo the call
+                // correctly instead of crashing the turn.
+                experimental_repairToolCall: async ({ toolCall, tools, error, messages, system }) => {
+                    if (!this.model)
+                        return null;
+                    try {
+                        const repair = await generateText({
+                            model: this.model,
+                            system,
+                            messages: [
+                                ...messages,
+                                {
+                                    role: "user",
+                                    content: `Your previous ${toolCall.toolName} tool call was rejected: ${error.message}. Call ${toolCall.toolName} again with ALL required arguments. (For write_file you must include both "path" — a filename — and "content".)`,
+                                },
+                            ],
+                            tools,
+                            toolChoice: "required",
+                            maxRetries: 1,
+                            abortSignal: this.controller?.signal,
+                            providerOptions: this.reasoningOptions(),
+                        });
+                        const fixed = repair.toolCalls.find((tc) => tc.toolName === toolCall.toolName) ??
+                            repair.toolCalls[0];
+                        if (!fixed)
+                            return null;
+                        return {
+                            toolCallType: "function",
+                            toolCallId: toolCall.toolCallId,
+                            toolName: fixed.toolName,
+                            args: JSON.stringify(fixed.args),
+                        };
+                    }
+                    catch {
+                        return null;
+                    }
+                },
+            });
+            let streamErrored = false;
+            for await (const part of result.fullStream) {
+                switch (part.type) {
+                    case "text-delta":
+                        this.emit("text-delta", part.textDelta);
+                        break;
+                    case "tool-call":
+                        this.emit("tool-call", {
+                            toolName: part.toolName,
+                            args: part.args,
+                        });
+                        break;
+                    case "tool-result":
+                        this.emit("tool-result", {
+                            toolName: part.toolName,
+                            result: part.result,
+                        });
+                        break;
+                    case "error":
+                        // The stream surfaced an error (e.g. a rate limit). The loop ends
+                        // here, but result.response would never resolve — awaiting it would
+                        // hang forever (busy stuck on "thinking…"). So bail out instead.
+                        streamErrored = true;
+                        this.emitError(part.error);
+                        break;
+                }
+            }
+            if (!streamErrored) {
+                const response = await result.response;
+                this.messages.push(...response.messages);
+            }
+        }
+        catch (err) {
+            this.emitError(err);
+        }
+        finally {
+            this.controller = null;
+            // Reset busy BEFORE emitting done so the UI never sees done while busy.
+            this.busy = false;
+            this.emit("done");
+        }
+    }
+}
+/**
+ * Build a detailed, human-readable error string. The Vercel AI SDK wraps the
+ * real failure in RetryError -> APICallError, where the actual provider reason
+ * (HTTP status + response body) lives. We unwrap that chain so errors like
+ * OpenRouter's "Provider returned error" show what really happened.
+ */
+function describeError(err) {
+    if (typeof err === "string")
+        return err;
+    // Tool-argument validation failures echo the entire (often huge) argument
+    // blob. Collapse them to a concise, actionable line.
+    const msg = err instanceof Error ? err.message : "";
+    if (/Invalid arguments for tool|Type validation failed|No such tool/i.test(msg)) {
+        const tool = /tool[: ]+["']?(\w+)/i.exec(msg)?.[1];
+        return `The model sent an invalid tool call${tool ? ` for ${tool}` : ""} and couldn't be repaired. Try again, or switch models with /model — some free models struggle with large file writes.`;
+    }
+    const parts = [];
+    const seen = new Set();
+    let e = err;
+    while (e && typeof e === "object" && !seen.has(e)) {
+        seen.add(e);
+        if (typeof e.statusCode === "number")
+            parts.push(`HTTP ${e.statusCode}`);
+        if (typeof e.message === "string" && e.message)
+            parts.push(e.message);
+        // The provider's raw error body usually holds the real reason.
+        const body = e.responseBody ?? e.data;
+        if (body) {
+            const text = typeof body === "string" ? body : safeJson(body);
+            if (text)
+                parts.push(text);
+        }
+        // Descend into wrapped errors (RetryError.lastError, Error.cause).
+        e = e.lastError ?? e.cause ?? undefined;
+    }
+    // De-duplicate (the wrapper message often repeats the inner one) and trim.
+    const seenText = new Set();
+    const unique = parts.filter((p) => {
+        const key = p.trim();
+        if (!key || seenText.has(key))
+            return false;
+        seenText.add(key);
+        return true;
+    });
+    let out = unique.join("\n");
+    if (out.length > 1500)
+        out = out.slice(0, 1500) + "…";
+    // Rate limits are the common free-tier failure — guide the user to options.
+    if (/\b429\b|rate.?limit/i.test(out)) {
+        out +=
+            "\n\nThis free model is busy. Retry in a moment, run /model to pick another free model, or add your own provider key with /key.";
+    }
+    return out || (err instanceof Error ? err.message : String(err));
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/agent/systemPrompt.js

@@ -0,0 +1,18 @@
+export function buildSystemPrompt(cwd) {
+    return `You are polycode, an open-source AI coding agent running in a terminal.
+You help the user with software engineering tasks in their project.
+
+Working directory: ${cwd}
+Operating system: ${process.platform}
+
+Guidelines:
+- Use the provided tools to read, search, write, and edit files, and to run shell commands. Do not guess file contents — read them.
+- Before editing a file, read it so your edits match the existing code exactly.
+- Prefer edit_file for small changes and write_file for new files.
+- write_file ALWAYS needs both "path" (a filename) and "content". For large files, write them in one complete call; don't omit the path.
+- When running commands, choose the smallest command that accomplishes the goal.
+- Explain what you are about to do briefly, then act. Keep prose concise.
+- After making changes, verify them (e.g. run tests or the build) when reasonable.
+- The user must approve file writes and shell commands; if a tool returns "Denied by user", stop and ask how to proceed.
+- Never invent file paths. Use search_code to locate things you are unsure about.`;
+}

package/dist/auth/keys.js

@@ -0,0 +1,35 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+const KEYS_PATH = join(homedir(), ".config", "polycode", "auth.json");
+function read() {
+    try {
+        return JSON.parse(readFileSync(KEYS_PATH, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Persist an API key locally and export it to the current process env. */
+export function saveKey(envVar, value) {
+    const store = read();
+    store[envVar] = value;
+    mkdirSync(dirname(KEYS_PATH), { recursive: true });
+    writeFileSync(KEYS_PATH, JSON.stringify(store, null, 2), "utf8");
+    process.env[envVar] = value;
+}
+export function clearKeys() {
+    try {
+        rmSync(KEYS_PATH);
+    }
+    catch {
+        /* nothing stored */
+    }
+}
+/** Load stored keys into the environment without overriding real env vars. */
+export function applyStoredKeys() {
+    for (const [envVar, value] of Object.entries(read())) {
+        if (value && !process.env[envVar])
+            process.env[envVar] = value;
+    }
+}

package/dist/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from "ink";
+import { App } from "./tui/App.js";
+import { loadConfig, findModel, globalConfigPath, openRouterModelConfig, } from "./config/config.js";
+import { buildModel, listModels, keyEnvFor, needsKey, ProviderError, } from "./providers/index.js";
+import { createTools } from "./tools/index.js";
+import { PermissionBroker } from "./tools/permissions.js";
+import { AgentSession } from "./agent/agent.js";
+import { applyStoredKeys, saveKey } from "./auth/keys.js";
+const VERSION = "0.1.0";
+function parseArgs(argv) {
+    const args = { yolo: false, model: "", help: false, version: false };
+    for (const a of argv) {
+        if (a === "--yolo" || a === "-y")
+            args.yolo = true;
+        else if (a === "--help" || a === "-h")
+            args.help = true;
+        else if (a === "--version" || a === "-v")
+            args.version = true;
+        else if (a.startsWith("--model="))
+            args.model = a.slice("--model=".length);
+    }
+    return args;
+}
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function printHelp() {
+    process.stdout.write(`polycode ${VERSION} — model-agnostic terminal coding agent
+
+Usage:
+  polycode [options]
+
+Options:
+  --model=<name>   Start with a specific configured model
+  --yolo, -y       Auto-approve all file writes and commands (use with care)
+  --version, -v    Print version and exit
+  --help, -h       Show this help
+
+Config: ${globalConfigPath()}
+
+Free open-source models (DeepSeek, GLM, Qwen, Llama, …):
+  • OpenRouter — get a FREE key (no credit card) at https://openrouter.ai/keys.
+    polycode will ask you to paste it on first run (or type /key anytime);
+    it's saved for next time. Run /model to browse all free models.
+  • Ollama — fully local & keyless: install https://ollama.com, then e.g.
+    \`ollama pull qwen3\` and pick a *-local model.
+
+You can also set keys as env vars: OPENROUTER_API_KEY, OPENAI_API_KEY, etc.
+
+Bring your own keys too: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY.
+`);
+}
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help)
+        return printHelp();
+    if (args.version)
+        return void process.stdout.write(`${VERSION}\n`);
+    const cwd = process.cwd();
+    applyStoredKeys(); // load any keys entered previously in the terminal
+    const { config, seeded } = loadConfig(cwd);
+    const broker = new PermissionBroker();
+    const tools = createTools(cwd, broker);
+    if (args.yolo) {
+        broker.allowAlways("write_file");
+        broker.allowAlways("edit_file");
+        broker.allowAlways("run_command");
+    }
+    const startName = args.model || config.defaultModel;
+    const startCfg = findModel(config, startName);
+    // Dynamic startup notices only — the title/help line lives in the banner.
+    const introLines = [];
+    if (seeded) {
+        introLines.push(`Seeded a default config at ${globalConfigPath()}.`);
+    }
+    // Does the starting model need a key we don't have yet? If so, we'll prompt
+    // for it right in the terminal instead of erroring out.
+    const startNeedsKey = !!startCfg && needsKey(startCfg) && !process.env[keyEnvFor(startCfg)];
+    let activeName = startName;
+    let initialModel = null;
+    let currentName = startName;
+    try {
+        if (!startCfg)
+            throw new ProviderError(`No model named "${startName}" in config.`);
+        initialModel = buildModel(startCfg);
+    }
+    catch (err) {
+        activeName = startCfg ? `${startName} (needs key)` : "none";
+        if (!startNeedsKey) {
+            introLines.push(msg(err));
+            introLines.push("Use /model to choose another, or /models to browse free models.");
+        }
+    }
+    const session = new AgentSession(initialModel, tools, cwd);
+    const switchModel = (name) => {
+        // Use a configured model if it exists; otherwise treat the name as a raw
+        // OpenRouter model id so any OpenRouter model works without editing config.
+        const cfg = findModel(config, name) ??
+            (process.env.OPENROUTER_API_KEY ? openRouterModelConfig(name) : undefined);
+        if (!cfg)
+            return {
+                ok: false,
+                message: `No model named "${name}". Set OPENROUTER_API_KEY to use any OpenRouter model, or see /models.`,
+            };
+        try {
+            session.setModel(buildModel(cfg));
+            currentName = name;
+            return { ok: true, message: `Switched to ${name}.`, name };
+        }
+        catch (err) {
+            return { ok: false, message: msg(err) };
+        }
+    };
+    // Save a key typed in the terminal to the env var of the current model's
+    // provider, then rebuild that model so it's ready immediately.
+    const onSaveKey = (key) => {
+        const cfg = findModel(config, currentName) ?? openRouterModelConfig(currentName);
+        saveKey(keyEnvFor(cfg), key);
+        return switchModel(currentName);
+    };
+    render(_jsx(App, { session: session, broker: broker, config: config, initialModel: activeName, switchModel: switchModel, listModels: listModels, onSaveKey: onSaveKey, promptKeyOnStart: startNeedsKey, version: VERSION, intro: introLines.length ? introLines.join("\n") : undefined }));
+}
+main();