npm - @legioncodeinc/rflectr - Versions diffs - 0.1.0 → 0.1.2 - Mend

@legioncodeinc/rflectr 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (69) hide show

package/library/knowledge/public/faqs/troubleshooting.md DELETED Viewed

@@ -1,92 +0,0 @@
-# Troubleshooting
-> Category: FAQ | Version: 1.0 | Date: June 2026 | Status: Active
-Common issues when launching **Claude Code** through `rflectr claude`. For Claude Desktop gateway issues, see the [Claude Desktop guide](../guides/claude-desktop.md). For agent/headless issues, see [AI Agents & automation](../guides/ai-agents.md).
----
-## "Not logged in · Please run /login" after picking a model
-**What you see:** Claude Code starts and shows the right model in the status bar (e.g. `moonshotai/kimi-k2.6`), but sending a message returns `Not logged in · Please run /login`.
-**Common cause — you chose "No" on the API key prompt.** When Claude Code detects an `ANTHROPIC_API_KEY` in the session (rflectr sets this for your chosen provider), it may ask:
-```text
-Detected a custom API key in your environment
-Do you want to use this API key?
-  1. Yes
-  2. No (recommended)
-```
-If you pick **No**, Claude Code remembers that and refuses to use the key. rflectr is routing through your provider correctly — Claude Code is blocking the key you rejected. This is **not** a rflectr bug and doesn't mean your provider is misconfigured.
-**Fix — approve the key in Claude Code's config.** Claude Code stores your answer in `~/.claude.json` under `customApiKeyResponses`.
-1. Quit Claude Code.
-2. Open `~/.claude.json`.
-3. Find the key suffix shown in the prompt (the last part of the masked key, e.g. `iFYB03v8xy4E-xJEYpN8`).
-4. Move that suffix from `rejected` to `approved`:
-```json
-"customApiKeyResponses": {
-  "approved": ["anything", "iFYB03v8xy4E-xJEYpN8"],
-  "rejected": []
-}
-```
-5. Save and run `rflectr claude` again.
-> 💡 **Easier next time:** choose **Yes** when the prompt appears — Claude Code remembers approved keys and won't ask again.
-**If you use Claude Max / Pro elsewhere:** you may also have a real Anthropic key in your shell (`~/.zshrc`, etc.). That's fine for other tools. rflectr replaces `ANTHROPIC_API_KEY` in the Claude Code child process with your **provider** key (OpenCode, Nvidia, Groq, …). Pick **Yes** when launching through rflectr.
----
-## Provider works in `rflectr models` but not in `providers list`
-Zen and Go are **cloud builtins** — they appear when you have an OpenCode API key, even if they aren't saved in `~/.rflectr/providers.json`. `rflectr providers list` shows them tagged `· cloud builtin`. Imported BYOK providers (Anthropic, Nvidia, Groq, …) come from the registry file.
----
-## OpenCode import saved placeholder API keys
-If you ran `rflectr providers import` on an older build and see refresh failures for Anthropic (`anything`) or Vertex (`a`), those came from **OpenCode's config**, not Claude Desktop.
-**Current behavior:** import validates keys before saving to the keychain:
-- Placeholders like `anything`, `a`, `ollama` → **not saved** (models still imported).
-- Real keys → probed against the provider API before save.
-- Vertex / Bedrock / Azure → key not saved (gcloud / AWS auth).
-**To clean up an old placeholder:** re-run import (choose **Use imported** for each provider), or remove the provider and import again:
-```bash
-rflectr providers import
-```
----
-## Use `--trace` for proxy / API errors
-If a model fails mid-session (not the login prompt above):
-```bash
-rflectr claude --trace
-```
-After exit, rflectr prints errors from `~/.rflectr/logs/claude-debug.log` (secrets redacted in the summary). The proxy also logs to `~/.rflectr/logs/proxy-debug.log` when `--trace` is set.
----
-## Still stuck?
-1. `rflectr providers list` — confirm the provider is there and enabled.
-2. `rflectr claude --dry-run` — preview provider, model, and endpoint without launching.
-3. Open a GitHub issue with the provider name, model id, and (redacted) error text.
----
-## Related guides
-- [Claude Desktop](../guides/claude-desktop.md) · [Codex](../guides/codex.md) · [AI Agents](../guides/ai-agents.md) · [Providers](../guides/providers.md)

package/library/knowledge/public/guides/README.md DELETED Viewed

@@ -1,13 +0,0 @@
-# Guides
-Step-by-step guides for each rflectr surface. New here? Read [What is rflectr?](../overview/what-is-rflectr.md) first.
-| Guide | Use it to… |
-|---|---|
-| [providers.md](providers.md) | See every provider, its base URL, and gotchas; add or import providers. |
-| [claude-desktop.md](claude-desktop.md) | Point Claude Desktop (Cowork + Code) at a local rflectr gateway, and revert cleanly. |
-| [codex.md](codex.md) | Run the OpenAI Codex CLI or desktop app on any registry model. |
-| [gemini-cli.md](gemini-cli.md) | Run the Google Gemini CLI on any registry model (experimental). |
-| [api-server.md](api-server.md) | Run the local Anthropic/OpenAI-compatible gateway (`rflectr server`). |
-| [ai-agents.md](ai-agents.md) | Drive rflectr from scripts, CI, and agents with boot flags and clean stdout. |
-| [model-compatibility.md](model-compatibility.md) | Understand why a model is hidden, and how to change that. |

package/library/knowledge/public/guides/ai-agents.md DELETED Viewed

@@ -1,273 +0,0 @@
-# AI Agents & Automation
-> Category: Guide | Version: 1.0 | Date: June 2026 | Status: Active
-rflectr is built so **AI agents** (scripts, CI, alef-agent, Cursor subagents, …) can launch Claude Code, OpenAI Codex, or Google Gemini CLI against your provider registry **without interactive wizards**, with **clean machine-readable stdout** when needed.
-For the full machine-readable reference — including your live provider/model list — run:
-```bash
-rflectr --ai
-rflectr --ai --install    # install SKILL.md to agent skill dirs
-```
----
-## Quick reference
-| Goal | Command |
-|---|---|
-| Agent reference | `rflectr --ai` |
-| Install agent skill | `rflectr --ai --install` |
-| Claude one-shot (text) | `rflectr claude --provider <id> --model <id> -p "prompt"` |
-| Claude NDJSON stream | `rflectr claude --provider <id> --model <id> -p "…" --output-format stream-json` |
-| Codex one-shot (text) | `rflectr codex --provider <id> --model <id> exec "prompt"` |
-| Codex JSONL events | `rflectr codex --provider <id> --model <id> exec --json "prompt"` |
-| Gemini one-shot (text) | `rflectr gemini --provider <id> --model <id> -p "prompt"` |
-| Gemini NDJSON stream | `rflectr gemini --provider <id> --model <id> -p "…" -o stream-json` |
-| Model slug | `--model zen__deepseek-v4-flash-free` (= `--provider zen --model deepseek-v4-flash-free`) |
-| List providers/models | `rflectr providers list` or read `~/.rflectr/providers.json` |
----
-## Boot flags (`--provider` / `--model`)
-rflectr consumes these flags **before** spawning the child. They are **not** passed through.
-| Flag | Purpose |
-|---|---|
-| `--provider <id>` | Registry provider id (`groq`, `google`, `zen`, `go`, …). |
-| `--model <id>` | Model id from that provider's cache. |
-| `--model <provider>__<model-id>` | Slug form — provider embedded in the model string. |
-### When the wizard is skipped
-- **Claude (`rflectr claude`):** both `--provider` and `--model` set, **or** print mode (`-p` / `--print`) with saved prefs from a prior interactive launch.
-- **Codex (`rflectr codex`):** both flags set, **or** non-interactive args (`exec` or a positional prompt) with saved prefs.
-- **Gemini (`rflectr gemini`):** both flags set, **or** non-interactive args (`-p`, `-i`, or a positional query) with saved prefs.
-> In CI / headless loops, **always pass `--provider` and `--model`** — never rely on saved prefs alone.
-### Examples
-```bash
-# Claude — explicit boot
-rflectr claude --provider groq --model llama-3.3-70b-versatile -p "Summarize README.md"
-# Claude — slug
-rflectr claude --model zen__deepseek-v4-flash-free -p "Review this diff"
-# Codex — explicit boot
-rflectr codex --provider openai --model gpt-5.4 exec "implement feature X"
-# Codex — slug
-rflectr codex --model zen__deepseek-v4-flash-free exec "fix the test"
-# Gemini — explicit boot
-rflectr gemini --provider google --model gemini-2.5-flash -p "Review this file"
-# Gemini — slug
-rflectr gemini --model zen__deepseek-v4-flash-free -p "Refactor the module"
-```
----
-## Clean stdout for NDJSON / JSONL
-When an agent parses **every line on stdout as JSON**, rflectr must not print boot UI (intro, spinner, proxy banners) on stdout. It detects machine-readable mode and **suppresses all boot UI on stdout** — messages still go to **stderr**.
-| Agent | Trigger | Child output |
-|---|---|---|
-| Claude | `-p` + `--output-format stream-json` or `json` | NDJSON (one object per line) |
-| Claude | `-p` + `--input-format stream-json` | NDJSON |
-| Codex | `exec --json` | JSONL event stream |
-| Gemini | `-p` + `-o stream-json` or `json` | NDJSON |
-> **Claude `--verbose`** is required by Claude Code for `stream-json` in print mode. rflectr **auto-adds `--verbose`** when it's missing.
-**Verify clean stdout:**
-```bash
-rflectr claude --provider zen --model deepseek-v4-flash-free \
-  -p "PONG" --output-format stream-json 2>/dev/null \
-  | node -e "process.stdin.on('data',d=>d.toString().split('\n').filter(Boolean).forEach(l=>JSON.parse(l))); console.log('ok')"
-```
-Interactive TTY launches (`rflectr claude` with no `-p`) still show the normal human UI.
----
-## Codex sandbox (network for shell tools)
-`rflectr codex` defaults to **`danger-full-access`** — written into the launch profile (`sandbox = "danger-full-access"`) and passed on spawn as `-s danger-full-access` (needed on macOS even when in the profile). This lets Codex shell tools reach the network (`curl`, `nlm`, npm, MCP CLIs).
-```bash
-rflectr codex -s workspace-write exec "task"                       # override for one session
-rflectr codex --dangerously-bypass-approvals-and-sandbox exec "x"  # bypass entirely (Codex flag)
-```
-`rflectr codex-app` does **not** change your personal `~/.codex/config.toml` sandbox. See [Codex § Sandbox](codex.md#sandbox-and-network-cli).
----
-## Provider discovery
-**Machine-readable catalog (recommended for agents):**
-```text
-~/.rflectr/providers.json
-  → providers[].id
-  → providers[].modelsCache.models[].id
-  → providers[].enabled
-```
-```bash
-rflectr providers refresh-models          # refresh all stale lists
-rflectr providers refresh-models groq      # refresh one provider
-```
-**Built-in cloud providers** (not in `providers.json`): `zen` and `go`, both requiring `OPENCODE_API_KEY`.
-**Preview without launching:**
-```bash
-rflectr claude --dry-run --provider groq --model llama-3.3-70b-versatile
-rflectr codex --config --provider zen --model deepseek-v4-flash-free
-```
----
-## Tool calling & MCP
-**Claude Code** — pass tool flags **after** rflectr's boot flags (they go to Claude):
-```bash
-rflectr claude --provider google --model gemini-2.5-flash \
-  -p "How many notebooks?" \
-  --output-format stream-json \
-  --allowed-tools mcp__notebooklm-mcp__notebook_list
-```
-**Codex** — MCP servers come from your Codex config (`~/.codex/config.toml`), not rflectr. With default `danger-full-access`, network-blocked MCP/CLI errors should be resolved; MCP must still be configured in Codex.
----
-## Multi-model agent loops
-```bash
-for model in llama-3.3-70b-versatile mixtral-8x7b-32768; do
-  rflectr claude --provider groq --model "$model" -p "Same prompt for all models"
-done
-for model in deepseek-v4-flash-free qwen3.6-plus-free; do
-  rflectr codex --provider zen --model "$model" exec --json "Same task"
-done
-for model in gemini-2.5-flash gemini-2.5-pro; do
-  rflectr gemini --provider google --model "$model" -p "Same task"
-done
-```
-Boot flags use **single-model launch** (the favorites catalog is skipped) — better for one-shot jobs. Use `rflectr models` + interactive launch for mid-session `/model` switching.
----
-## Zen / Go cloud providers
-For Claude `-p` and Codex `exec` against OpenCode Zen or Go:
-- Pass `--provider zen` or `--provider go` explicitly in agent configs.
-- Ensure `OPENCODE_API_KEY` is in the environment or OS keychain (rflectr resolves it before launch).
----
-## Codex proxy notes (DeepSeek / reasoning models)
-Non-OpenAI models routed through rflectr's Codex proxy use the Responses API adapter. **Reasoning content** from thinking models (e.g. DeepSeek) is round-tripped on tool loops, so turn 2+ doesn't fail with missing `reasoning_content`.
----
-## alef-agent integration
-alef-agent shells out to CLI backends and parses **NDJSON/JSONL on stdout**. Use rflectr as the **wrapper executable** with boot flags prepended.
-**Claude backend (stream-json):**
-```bash
-rflectr claude --provider <id> --model <id> -p "<prompt>" \
-  --output-format stream-json [--verbose] \
-  [--max-turns, --permission-mode, --allowed-tools, …]
-```
-**Codex backend (exec --json):**
-```bash
-rflectr codex --provider <id> --model <id> exec --json "<prompt>" [codex flags]
-```
-**Gemini backend (stream-json):**
-```bash
-rflectr gemini --provider <id> --model <id> -p "<prompt>" -o stream-json [gemini flags]
-```
-### Checklist
-1. **Executable:** `rflectr` on `PATH` (`npm link` after dev builds).
-2. **Always set** `--provider` + `--model` (or a slug on `--model`).
-3. **Claude:** use `--output-format stream-json`; rflectr adds `--verbose` if needed.
-4. **Codex:** use `exec --json` — **not** `-p` (in Codex, `-p` means profile).
-5. **Gemini:** use `-o stream-json` or `-o json` with `-p`.
-6. **Parse stdout only** — boot/errors go to stderr in machine-readable mode.
-7. **Codex network:** the default sandbox is already full access; no extra `-s` needed.
-8. **Discovery:** run `rflectr --ai` or read `providers.json` to populate model lists.
-9. **Skill:** `rflectr --ai --install` drops `rflectr-cli/SKILL.md` into agent skill dirs.
-### Stdout contract
-```text
-stderr  → rflectr boot/errors (safe to log; ignore for parsing)
-stdout  → child NDJSON/JSONL only (when stream-json / exec --json)
-exit    → rflectr exit code (non-zero on launch/config errors)
-```
-The full alef section is also embedded at the bottom of `rflectr --ai`.
----
-## Agent rules of thumb
-**Do:**
-- Run `rflectr --ai` when unsure.
-- Use `--provider` + `--model` for every headless invocation.
-- Use Claude `-p` / Codex `exec` for one-shots that must exit.
-- Read `providers.json` for authoritative model ids.
-- Send machine-readable flags so stdout stays parseable.
-**Don't:**
-- Rely on interactive wizards in CI or agent loops.
-- Pass `--provider` / `--model` to Claude/Codex/Gemini directly — rflectr consumes them.
-- Use Codex `-p` for print mode (it's `--profile` in Codex).
-- Expect the favorites catalog in print/exec mode — use explicit boot flags.
-- Edit `~/.claude/settings.json`, `~/.gemini/config/config.json`, or `~/.codex/config.toml` from rflectr — it uses env + temporary overlays.
----
-## Troubleshooting (agents)
-| Symptom | Fix |
-|---|---|
-| JSON parse error on first stdout lines | Missing `--output-format stream-json` (Claude) or `exec --json` (Codex). |
-| `Print mode requires --provider and --model` | Add boot flags, or run interactive once to save prefs. |
-| `requires an interactive terminal` (Codex) | Add `--provider` and `--model`. |
-| Zen/Go "Not logged in" | Set `OPENCODE_API_KEY`; pass `--provider zen` explicitly. |
-| Codex shell network blocked | Should be default; confirm `rflectr codex --config` shows `sandbox = "danger-full-access"`. |
-| DeepSeek tool loop 400 | Update rflectr — reasoning round-trip fix in the Codex proxy. |
-| Stale overlay after crash | `rflectr codex --restore`. |
-See [Troubleshooting](../faqs/troubleshooting.md) for general rflectr issues.
----
-## Related guides
-- [Codex](codex.md) · [Gemini CLI](gemini-cli.md) · [Providers](providers.md) · [Troubleshooting](../faqs/troubleshooting.md)

package/library/knowledge/public/guides/api-server.md DELETED Viewed

@@ -1,108 +0,0 @@
-# API Server
-> Category: Guide | Version: 1.0 | Date: June 2026 | Status: Active
-`rflectr server` runs a local gateway that bridges your model backends (OpenCode Zen, Go, registry providers, or Vertex AI) to any client that speaks the Anthropic or OpenAI API. Both formats are served on one port.
----
-## Start the server
-```bash
-rflectr server            # registry / Zen / Go providers
-rflectr server --vertex   # Claude on Google Vertex AI via gcloud ADC
-```
-The server runs an interactive wizard (password setup, which providers to expose, optional favorites-only catalog, discovery-id masking) and then listens. Default port: **17645**.
-```text
-Rflectr server running
-  Anthropic:  http://127.0.0.1:17645/anthropic
-  OpenAI:     http://127.0.0.1:17645/openai/v1
-  Network (en0):
-    Anthropic:  http://192.168.68.70:17645/anthropic
-    OpenAI:     http://192.168.68.70:17645/openai/v1
-  API key:    saved, rotate with `rflectr server --setup`
-  Catalog:    favorite models only
-```
----
-## Reading the model catalog
-On startup the server prints every exposed model with **two identifiers**:
-```text
-  Google Gemini
-    gemini-3.5-flash
-      anthropic: anthropic-google__gemini-3.5-flash
-      openai:    gemini-3.5-flash
-  OpenCode Go
-    Kimi K2.7 Code
-      anthropic: anthropic-go__kimi-k2.7-code
-      openai:    kimi-k2.7-code
-```
-| Identifier | Use it when your client expects… |
-|---|---|
-| `anthropic:` | Anthropic-format requests (Anthropic SDK, Claude Code, Claude Desktop). |
-| `openai:` | OpenAI-format requests (OpenAI SDK, OpenAI-compatible extensions). |
----
-## Endpoints
-| Method + path | Purpose |
-|---|---|
-| `GET /health` | Liveness check. |
-| `GET /anthropic/v1/models` · `GET /openai/v1/models` | List exposed models. |
-| `POST /anthropic/v1/messages` | Anthropic Messages relay. |
-| `POST /openai/v1/chat/completions` | OpenAI Chat Completions relay. |
-Base URLs for clients:
-- **Anthropic:** `http://127.0.0.1:17645/anthropic`
-- **OpenAI:** `http://127.0.0.1:17645/openai/v1`
-> ⚠️ **Do not append `/v1` to the Anthropic base URL** — the Anthropic SDK adds API paths itself.
----
-## Connecting a client
-Most OpenAI-compatible tools just need a base URL and (optionally) the server password as the API key. Example — **[THE AI Counsel](https://github.com/legioncodeinc/the-ai-counsel)**:
-1. Open **Settings → LLM API Keys → Custom OpenAI-Compatible Endpoint**.
-2. **Display Name:** anything descriptive (e.g. `Rflectr Server`).
-3. **Base URL:**
-   - Same machine: `http://127.0.0.1:17645/openai/v1`
-   - Another device on your LAN: `http://<server-ip>:17645/openai/v1` (use an IP printed at startup).
-4. **API Key:** the server password if one is set, otherwise leave empty.
-5. Click **Connect** to fetch the gateway's models.
----
-## Vertex AI mode
-`rflectr server --vertex` exposes Claude on Google Vertex AI using your local `gcloud` Application Default Credentials — no OpenCode key needed.
-| Env var | Purpose |
-|---|---|
-| `ANTHROPIC_VERTEX_PROJECT_ID` or `GOOGLE_CLOUD_PROJECT` | Your GCP project. |
-| `GOOGLE_CLOUD_LOCATION` or `CLOUD_ML_REGION` | Region (default `global`). |
-Optional model catalog override: `~/.rflectr/vertex-models.json` (see `assets/vertex-models.example.json`).
----
-## Auth
-- **Local mode:** any non-empty bearer token / `x-api-key` works.
-- **Network mode:** the wizard sets a **server password** — it's the only gate once the port is reachable beyond localhost, so treat it as a secret.
----
-## Related guides
-- [Claude Desktop setup](claude-desktop.md) (uses this gateway) · [Providers](providers.md) · [Troubleshooting](../faqs/troubleshooting.md)