@muthuishere/routsi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muthukumaran Navaneethakrishnan
+
+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,158 @@
+# routsi
+
+One OpenAI-compatible endpoint that routes each request to the right **model or
+agent** — API models (OpenRouter, OpenAI, DeepSeek, …) *and* local agent CLIs
+(Devin, Codex, Copilot, Claude Code) — with per-task routing, per-conversation
+stickiness, a live dashboard, and metrics. A single Go binary; point any OpenAI SDK
+at it.
+
+## Quick start
+
+```sh
+task build                       # -> bin/routsi
+cp models.yaml ~/.config/routsi/ # or keep ./models.yaml
+routsi serve                     # listens on :8080 by default
+```
+
+### Install via npm
+
+```sh
+npm install -g @muthuishere/routsi
+```
+
+`postinstall` downloads the prebuilt `routsi` binary for your OS/arch from [GitHub
+Releases](https://github.com/muthuishere/routsi/releases) — no Go toolchain needed.
+See [`docs/adr/006-npm-distribution.md`](docs/adr/006-npm-distribution.md) for how it
+works.
+
+Point any OpenAI client at `http://localhost:8080/v1`. Then:
+
+```sh
+curl localhost:8080/v1/chat/completions -H 'content-type: application/json' \
+  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'
+```
+
+- **`model: "auto"`** — routsi classifies the task and picks a tier.
+- **`model: "dynamic-1"`** — a named group you define (low/medium/high members).
+- **`model: "openrouter/anthropic/claude-haiku-4.5"`** — a concrete model, no routing.
+- **`model: "devin/opus"`** — an agent as a model.
+
+### Forwarding to an agent model (devin/…)
+
+Agent CLIs expose their inner models as `<agent>/<model>` catalog entries — from
+`variants:` or discovery (`GET /v1/models` lists them all). Just name one:
+
+```sh
+curl localhost:8080/v1/chat/completions -H 'content-type: application/json' \
+  -H 'X-Conversation-Id: my-thread-1' \
+  -d '{"model":"devin/claude-opus-4.8","messages":[{"role":"user","content":"refactor plan?"}]}'
+```
+
+`devin/claude-opus-4.8` runs `devin --model claude-opus-4.8`; the conversation id maps
+to a real Devin session (`-r` resume on later turns). Bare `devin` uses the default
+model. Same pattern for `codex/…`, `copilot/…`, `claude/…` (one-shot). A dynamic
+group level can point at an agent too: `high: devin/claude-opus-4.8`.
+
+## Auth (token or mTLS)
+
+Generate tokens with the built-in CLI:
+
+```sh
+routsi token -n 2      # prints rtk_... tokens + setup instructions
+```
+
+For mTLS, generate the whole trust setup (CA + server + client certs) in one command:
+
+```sh
+routsi certs                        # -> ~/.config/routsi/certs/ (keys 0600)
+routsi certs -host myhost.example   # extra server SANs
+```
+
+```yaml
+auth:
+  tokens_env: ROUTSI_TOKENS   # export ROUTSI_TOKENS="tok1,tok2" — enables bearer auth
+tls:
+  cert: server.crt            # cert+key = HTTPS
+  key: server.key
+  client_ca: clients-ca.crt   # + client_ca = mTLS (client certs required)
+```
+
+With tokens on: `/v1/*`, `/stats`, `/metrics` need `Authorization: Bearer <tok>`
+(OpenAI SDKs send this automatically as the api_key); dashboard: `/?token=tok`.
+`/health` stays open. Token values live in env vars, never in the config file.
+
+**Secrets via `.env`:** on startup routsi layers env vars, highest priority first:
+process env > `-env`/`ROUTSI_ENV_FILE` > `./.env` > `~/.config/routsi/.env`. A file
+never overrides a higher source and values are never logged — so provider keys and
+`ROUTSI_TOKENS` can live in whichever `.env` suits you instead of your shell profile.
+Keep the file `chmod 600` and out of version control.
+
+The chosen model is returned in the `X-Selected-Model` header. Every response
+carries a `usage` block.
+
+## Pull-workers: let anyone plug in their agent
+
+Instead of routsi hosting an agent CLI, a **remote worker** can join and answer — run
+your own opencode/codex/claude anywhere, register a queue, answer questions the proxy
+routes to it. Credentials never leave your machine; the worker is outbound-only.
+
+```sh
+# on the worker machine (any machine with your agent logged in):
+routsi worker run --proxy https://your-proxy:8080 --queue my-agent \
+  --agent 'codex exec --skip-git-repo-check -'    # reads the question on stdin, prints the answer
+```
+
+Now `{"model":"my-agent"}` routes to that worker. It's a normal model — shows in
+`/v1/models`, `GET /v1/workers` (live status: state, last-seen, served, errors), and the
+dashboard Workers panel. If no worker is live, requests fast-fail with `503`. No worker
+auth in v1 (reserved `workers.auth` config placeholder). `routsi worker scaffold` prints
+an editable curl-only version.
+
+Install the worker as an **agent skill** so any agent session can become a worker:
+
+```sh
+routsi install --skills     # into ~/.claude/skills and ~/.codex/skills
+```
+
+## Run it as a service (watchdog)
+
+Keeps routsi up across crashes and logins — launchd on macOS, systemd-user on Linux:
+
+```sh
+routsi install     # install + start (restart-on-failure, start-at-login)
+routsi status      # is it running?
+routsi uninstall   # stop + remove
+```
+
+No root; everything lives under your home dir. macOS logs: `~/Library/Logs/routsi.log`.
+
+## Dashboard & metrics
+
+- **`http://localhost:8080/`** — live dashboard (requests, tokens, latency, routing
+  split, escalations), auto-refreshing, self-contained.
+- **`/stats`** — JSON snapshot.
+- **`/metrics`** — Prometheus text (scrape it).
+
+## Config (`models.yaml`)
+
+See the commented [`models.yaml`](models.yaml). Highlights:
+
+- `type: forward` — any OpenAI-compatible upstream (raw byte passthrough).
+- `type: devin|codex|copilot|claude` — local agent CLIs (must be installed + logged in).
+- `type: dynamic` — a virtual model with `levels: {low, medium, high}`.
+- `variants:` / `discover_models: true` — expand one entry into many models. Forwards
+  fetch upstream `GET /models`; Devin is probed live; codex/copilot/claude read
+  `~/.config/routsi/known-models.json` (editable).
+
+## How it differs from LiteLLM / OpenRouter / other gateways
+
+Gateways route between *providers serving the same model* (load-balance, fallback).
+routsi routes between *fundamentally different answerers* — API models **and full
+agents** — behind one OpenAI face, choosing by task, sticky per conversation. It's a
+single dependency-light binary you run yourself, not a platform.
+
+## Design notes
+
+Routing/conversation decisions are grounded in `docs/research/`. Not yet built:
+inbound auth, tool-call passthrough on enveloped paths, escalation memory handoff,
+compaction. See `CLAUDE.md` for current state.

package/npm/launcher.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+'use strict';
+
+// Thin launcher installed as the `routsi` bin entry. Execs the native binary
+// downloaded by scripts/postinstall.js into npm/bin/, passing argv/stdio/exit
+// code straight through. Kept separate from the Go build's own `bin/routsi`
+// output so `task build` (repo checkout) and this npm package never collide.
+
+const path = require('path');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+const binName = process.platform === 'win32' ? 'routsi.exe' : 'routsi';
+const binPath = path.join(__dirname, 'bin', binName);
+
+if (!fs.existsSync(binPath)) {
+  console.error(
+    `routsi: native binary not found at ${binPath}.\n` +
+    'The postinstall step may have failed or been skipped (offline install?).\n' +
+    'Try: npm install -g routsi --force\n' +
+    'Or download a binary manually from https://github.com/muthuishere/routsi/releases'
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binPath, process.argv.slice(2), { stdio: 'inherit' });
+
+if (result.error) {
+  console.error('routsi: failed to launch native binary: ' + result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@muthuishere/routsi",
+  "version": "0.1.0",
+  "description": "OpenAI-compatible dynamic LLM router — a single Go binary, installed via npm as a prebuilt native binary",
+  "license": "MIT",
+  "bin": {
+    "routsi": "npm/launcher.js"
+  },
+  "files": [
+    "npm",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muthuishere/routsi.git"
+  },
+  "homepage": "https://muthuishere.github.io/routsi",
+  "bugs": {
+    "url": "https://github.com/muthuishere/routsi/issues"
+  },
+  "keywords": [
+    "llm",
+    "router",
+    "openai",
+    "proxy",
+    "ai"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+'use strict';
+
+// Zero-dependency postinstall: downloads the prebuilt routsi binary for this
+// OS/arch from GitHub Releases and drops it at npm/bin/routsi[.exe].
+//
+// Asset naming scheme (MUST match .github/workflows/release.yml):
+//   routsi_<os>_<arch>.tar.gz   (darwin/linux)
+//   routsi_windows_<arch>.zip  (windows)
+// where <os> in {darwin, linux, windows}, <arch> in {amd64, arm64}.
+// Release URL: https://github.com/muthuishere/routsi/releases/download/v<version>/<asset>
+// Each release also carries a checksums.txt (sha256sum output) covering all assets.
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const zlib = require('zlib');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+const REPO = 'muthuishere/routsi';
+const PKG_ROOT = path.join(__dirname, '..');
+const BIN_DIR = path.join(PKG_ROOT, 'npm', 'bin');
+
+function pkgVersion() {
+  const pkg = require(path.join(PKG_ROOT, 'package.json'));
+  return pkg.version;
+}
+
+// Pure mapping function — unit-tested by scripts/postinstall.test.js.
+// platform: node's os.platform() value ('darwin'|'linux'|'win32'|...)
+// arch: node's os.arch() value ('x64'|'arm64'|...)
+function mapPlatform(platform) {
+  if (platform === 'darwin') return 'darwin';
+  if (platform === 'linux') return 'linux';
+  if (platform === 'win32') return 'windows';
+  return null;
+}
+
+function mapArch(arch) {
+  if (arch === 'x64') return 'amd64';
+  if (arch === 'arm64') return 'arm64';
+  return null;
+}
+
+function assetName(platform, arch, version) {
+  const os_ = mapPlatform(platform);
+  const arch_ = mapArch(arch);
+  if (!os_ || !arch_) {
+    throw new Error(`unsupported platform/arch: ${platform}/${arch}`);
+  }
+  const ext = os_ === 'windows' ? 'zip' : 'tar.gz';
+  return `routsi_${os_}_${arch_}.${ext}`;
+}
+
+function binaryName(platform) {
+  return mapPlatform(platform) === 'windows' ? 'routsi.exe' : 'routsi';
+}
+
+function releaseUrl(version, asset) {
+  return `https://github.com/${REPO}/releases/download/v${version}/${asset}`;
+}
+
+function isOffline() {
+  if (process.env.npm_config_offline === 'true') return true;
+  if (process.env.npm_config_prefer_offline === 'true' && process.env.ROUTSI_ALLOW_STALE) return true;
+  return false;
+}
+
+function fail(msg) {
+  console.error('\nroutsi postinstall: ' + msg);
+  console.error(
+    `See release assets at https://github.com/${REPO}/releases — you can also\n` +
+    'download the right binary by hand and place it on your PATH.\n'
+  );
+  process.exit(1);
+}
+
+function warnSkip(msg) {
+  console.warn('routsi postinstall: ' + msg + ' — skipping download.');
+  process.exit(0);
+}
+
+// GET with a bounded number of redirect hops. Returns a Buffer via callback.
+function fetchBuffer(url, redirectsLeft, cb) {
+  const req = https.get(url, { headers: { 'User-Agent': 'routsi-npm-postinstall' } }, (res) => {
+    if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+      if (redirectsLeft <= 0) {
+        cb(new Error('too many redirects fetching ' + url));
+        return;
+      }
+      res.resume();
+      fetchBuffer(res.headers.location, redirectsLeft - 1, cb);
+      return;
+    }
+    if (res.statusCode !== 200) {
+      res.resume();
+      cb(new Error(`GET ${url} -> HTTP ${res.statusCode}`));
+      return;
+    }
+    const chunks = [];
+    res.on('data', (c) => chunks.push(c));
+    res.on('end', () => cb(null, Buffer.concat(chunks)));
+    res.on('error', cb);
+  });
+  req.on('error', cb);
+}
+
+function fetchBufferAsync(url) {
+  return new Promise((resolve, reject) => {
+    fetchBuffer(url, 5, (err, buf) => (err ? reject(err) : resolve(buf)));
+  });
+}
+
+// Best-effort checksum verification. If checksums.txt can't be fetched (e.g.
+// older release, network hiccup), we proceed without failing the install.
+async function verifyChecksum(version, assetBuf, asset) {
+  let checksumsBuf;
+  try {
+    checksumsBuf = await fetchBufferAsync(releaseUrl(version, 'checksums.txt'));
+  } catch (err) {
+    console.warn('routsi postinstall: could not fetch checksums.txt (' + err.message + '), skipping verification');
+    return;
+  }
+  const text = checksumsBuf.toString('utf8');
+  const line = text.split('\n').find((l) => l.trim().endsWith(asset));
+  if (!line) {
+    console.warn('routsi postinstall: no checksum entry for ' + asset + ', skipping verification');
+    return;
+  }
+  const expected = line.trim().split(/\s+/)[0].toLowerCase();
+  const actual = crypto.createHash('sha256').update(assetBuf).digest('hex');
+  if (expected !== actual) {
+    fail(`checksum mismatch for ${asset}: expected ${expected}, got ${actual}`);
+  }
+}
+
+function extractTarGz(buf, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const tmpTar = path.join(os.tmpdir(), `routsi-${Date.now()}.tar.gz`);
+  fs.writeFileSync(tmpTar, buf);
+  try {
+    execFileSync('tar', ['-xzf', tmpTar, '-C', destDir], { stdio: 'inherit' });
+  } finally {
+    fs.rmSync(tmpTar, { force: true });
+  }
+}
+
+function extractZip(buf, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const tmpZip = path.join(os.tmpdir(), `routsi-${Date.now()}.zip`);
+  fs.writeFileSync(tmpZip, buf);
+  try {
+    if (process.platform === 'win32') {
+      execFileSync('powershell.exe', [
+        '-NoProfile', '-Command',
+        `Expand-Archive -Force -Path "${tmpZip}" -DestinationPath "${destDir}"`,
+      ], { stdio: 'inherit' });
+    } else {
+      execFileSync('unzip', ['-o', tmpZip, '-d', destDir], { stdio: 'inherit' });
+    }
+  } finally {
+    fs.rmSync(tmpZip, { force: true });
+  }
+}
+
+// Locate the extracted binary — tarball/zip is flat (no top-level dir), but
+// tolerate one either way.
+function findExtractedBinary(destDir, wantName) {
+  const direct = path.join(destDir, wantName);
+  if (fs.existsSync(direct)) return direct;
+  const entries = fs.readdirSync(destDir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      const nested = path.join(destDir, e.name, wantName);
+      if (fs.existsSync(nested)) return nested;
+    }
+  }
+  return null;
+}
+
+async function main() {
+  const platform = process.platform;
+  const arch = process.arch;
+  const version = pkgVersion();
+  const finalBinPath = path.join(BIN_DIR, binaryName(platform));
+
+  if (fs.existsSync(finalBinPath) && fs.statSync(finalBinPath).size > 0) {
+    console.log('routsi postinstall: binary already present at ' + finalBinPath + ', skipping download');
+    return;
+  }
+
+  if (isOffline()) {
+    warnSkip('offline mode requested (npm_config_offline)');
+    return;
+  }
+
+  let asset;
+  try {
+    asset = assetName(platform, arch, version);
+  } catch (err) {
+    fail(
+      `${err.message}. routsi ships prebuilt binaries for darwin/linux/windows on amd64/arm64.\n` +
+      'Build from source instead: https://github.com/' + REPO
+    );
+    return;
+  }
+
+  const url = releaseUrl(version, asset);
+  console.log(`routsi postinstall: downloading ${asset} from ${url}`);
+
+  let assetBuf;
+  try {
+    assetBuf = await fetchBufferAsync(url);
+  } catch (err) {
+    fail(`failed to download ${url}: ${err.message}`);
+    return;
+  }
+
+  await verifyChecksum(version, assetBuf, asset);
+
+  const extractDir = fs.mkdtempSync(path.join(os.tmpdir(), 'routsi-extract-'));
+  try {
+    if (asset.endsWith('.zip')) {
+      extractZip(assetBuf, extractDir);
+    } else {
+      extractTarGz(assetBuf, extractDir);
+    }
+
+    const wantName = binaryName(platform);
+    const extracted = findExtractedBinary(extractDir, wantName);
+    if (!extracted) {
+      fail(`downloaded archive ${asset} did not contain expected binary ${wantName}`);
+      return;
+    }
+
+    fs.mkdirSync(BIN_DIR, { recursive: true });
+    fs.copyFileSync(extracted, finalBinPath);
+    fs.chmodSync(finalBinPath, 0o755);
+    console.log('routsi postinstall: installed binary at ' + finalBinPath);
+  } finally {
+    fs.rmSync(extractDir, { recursive: true, force: true });
+  }
+}
+
+if (require.main === module) {
+  main().catch((err) => fail(err && err.message ? err.message : String(err)));
+}
+
+module.exports = { assetName, mapPlatform, mapArch, binaryName, releaseUrl };

package/scripts/postinstall.test.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+'use strict';
+
+// Tiny assertion check for the pure platform->asset mapping in postinstall.js.
+// Run with: node scripts/postinstall.test.js
+
+const assert = require('assert');
+const { assetName, binaryName, releaseUrl } = require('./postinstall.js');
+
+function eq(actual, expected, label) {
+  assert.strictEqual(actual, expected, `${label}: expected ${expected}, got ${actual}`);
+  console.log(`ok - ${label}`);
+}
+
+eq(assetName('darwin', 'arm64', '0.1.0'), 'routsi_darwin_arm64.tar.gz', 'darwin/arm64 asset name');
+eq(assetName('darwin', 'x64', '0.1.0'), 'routsi_darwin_amd64.tar.gz', 'darwin/amd64 asset name');
+eq(assetName('linux', 'x64', '0.1.0'), 'routsi_linux_amd64.tar.gz', 'linux/amd64 asset name');
+eq(assetName('linux', 'arm64', '0.1.0'), 'routsi_linux_arm64.tar.gz', 'linux/arm64 asset name');
+eq(assetName('win32', 'x64', '0.1.0'), 'routsi_windows_amd64.zip', 'windows/amd64 asset name');
+
+eq(binaryName('darwin'), 'routsi', 'darwin binary name');
+eq(binaryName('win32'), 'routsi.exe', 'windows binary name');
+
+eq(
+  releaseUrl('0.1.0', 'routsi_linux_amd64.tar.gz'),
+  'https://github.com/muthuishere/routsi/releases/download/v0.1.0/routsi_linux_amd64.tar.gz',
+  'release URL construction'
+);
+
+assert.throws(() => assetName('sunos', 'x64', '0.1.0'), /unsupported platform\/arch/, 'unsupported platform throws');
+assert.throws(() => assetName('linux', 'ia32', '0.1.0'), /unsupported platform\/arch/, 'unsupported arch throws');
+
+console.log('\nall postinstall mapping checks passed');