llm-relay 0.35.0 → 0.37.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OhOkThisIsFine
+
+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

@@ -11,6 +11,7 @@ weaker (often free) models.
 ```bash
 npm install -g llm-relay
 llm-relay onboard          # collect free provider keys (NIM, Groq, Gemini, OpenRouter, ...)
+llm-relay onboard --import keys.env  # import dotenv or a FreeLLMAPI export JSON
 llm-relay setup claude-desktop   # or: llm-relay setup claude-cli
 llm-relay                  # start the proxy — leave it running
 ```
@@ -22,12 +23,20 @@ llm-relay keys             # are the credentials good?
 llm-relay pools --probe    # does every configured model actually answer?
 ```
 
+With the relay still running, open its local read-only analytics in another terminal:
+
+```bash
+llm-relay dashboard
+```
+
 New here? [docs/QUICKSTART.md](docs/QUICKSTART.md) is a staged setup guide you can hand
 straight to an AI assistant ("set this up for me"). It also covers keeping the relay running
 at login.
 
 ## What you get
 
+- **Credential fleets** — give one provider multiple labeled, env-backed keys; the relay walks
+  slots breadth-first and keeps account faults and limits separate. [Configure fleets](docs/reference.md#provider-credential-fleets).
 - **Pools with failover** — `model: "pool/medium"` expands to a ranked candidate list; 429s
   and outages cascade to the next member. Free-model pools update themselves from live catalogs.
 - **Passthrough** — Claude traffic keeps your own credentials and reaches real Anthropic
@@ -39,6 +48,9 @@ at login.
   tool calls are refused, never fabricated; unrepairable calls fail clean.
 - **Both API fronts** — Anthropic `/v1/messages` plus OpenAI `/v1/chat/completions` and
   `/v1/responses`, translated in either direction, streaming included.
+- **Local analytics dashboard** — `llm-relay dashboard` opens bounded request/attempt, token,
+  latency, provider/model/client/credential, quota, and cooldown views. Unknown or unavailable
+  accounting remains explicit; the dashboard never guesses a value or starts provider probes.
 - **Honest metadata** — per-deployment limits and prices with provenance, capability scores
   synced from four leaderboards, metadata-only logging, loopback-only binding.
 

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,72 @@
+# Third-party notices
+
+The dashboard is compiled locally and does not load application code, fonts, images, or other
+media from a CDN. This notice covers source packages physically represented in the production
+dashboard bundle, generated CSS assets, and generated virtual-runtime helpers. The checked
+inventory is `docs/dashboard-bundle-inventory.json`; `scripts/dashboard-package-check.mjs`
+compares its JavaScript package list to Vite/Rollup's production module graph and validates the
+manual generated-output attributions.
+
+## Emitted package modules
+
+| Package | License | Attribution |
+| --- | --- | --- |
+| `lucide-react@0.468.0` | ISC | Portions of Lucide are held by Cole Bemis 2013-2022 as part of Feather (MIT). All other Lucide copyright is held by Lucide Contributors 2022. |
+| `react@19.2.8` | MIT | Copyright (c) Meta Platforms, Inc. and affiliates |
+| `react-dom@19.2.8` | MIT | Copyright (c) Meta Platforms, Inc. and affiliates |
+| `scheduler@0.27.0` | MIT | Copyright (c) Meta Platforms, Inc. and affiliates |
+
+## Generated stylesheet assets
+
+| Asset source | Attribution | License |
+| --- | --- | --- |
+| Tailwind Preflight, components and utilities emitted from `dashboard/src/styles.css` | `tailwindcss@3.4.19`, Copyright (c) Tailwind Labs, Inc. | MIT |
+
+## Generated virtual-runtime helpers
+
+| Virtual module | Attribution | License |
+| --- | --- | --- |
+| `vite/modulepreload-polyfill.js` | `vite@6.4.3`, Copyright (c) 2019-present VoidZero, Inc. and Vite contributors | MIT |
+
+Dependencies not physically included in the dashboard bundle are not represented by this
+dashboard-specific notice.
+
+## MIT License
+
+MIT License
+
+Copyright (c) the copyright holders identified above
+
+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.
+
+## ISC License
+
+Copyright (c) the copyright holders identified above
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/config.example.json

@@ -4,7 +4,10 @@
     "nim": {
       "base": "https://integrate.api.nvidia.com/v1",
       "kind": "openai",
-      "authEnv": "NVIDIA_API_KEY",
+      "credentials": [
+        { "label": "personal", "authEnv": "NVIDIA_API_KEY" },
+        { "label": "work", "authEnv": "NVIDIA_WORK_API_KEY" }
+      ],
       "tierType": "free"
     },
     "openrouter": {
@@ -77,7 +80,8 @@
     "offload": {
       "claude": { "enabled": false, "scope": "subagents" },
       "codex": { "enabled": false, "scope": "subagents" }
-    }
+    },
+    "sticky": false
   },
   "mode": "repair",
   "repair": {
@@ -89,6 +93,8 @@
       "Edit",
       "MultiEdit",
       "NotebookEdit",
+      "shell_command",
+      "apply_patch",
       "rm",
       "delete",
       "delete_file",

package/dist/accounting-store-io.d.ts

@@ -0,0 +1,124 @@
+/**
+ * A deliberately small durability primitive for accounting's multi-file read model.
+ *
+ * It writes a full snapshot journal before replacing any target.  A later process can
+ * therefore replay the journal after any target-write prefix without applying a delta
+ * twice.  This module knows nothing about accounting's schemas; callers supply already
+ * materialised snapshots and an explicit target allow-list. Only flat, portable direct
+ * children of the root are supported for targets and the journal.
+ *
+ * Threat model: the root and its parent must be trusted and non-adversarial against
+ * concurrent same-user replacement. Race-proof filesystem containment against an actor
+ * able to rename or replace the root is out of scope; root and final reparse points are
+ * still checked before filesystem operations. Writer ownership is enforced only among
+ * instances in this process; cross-process concurrent writers are unsupported.
+ */
+export declare const SNAPSHOT_JOURNAL_SCHEMA = "llm-relay.snapshot-journal.v1";
+export declare const SNAPSHOT_JOURNAL_VERSION = 1;
+export declare const SNAPSHOT_IO_DEFAULT_MAX_FILE_BYTES: number;
+export declare const SNAPSHOT_IO_DEFAULT_MAX_JOURNAL_BYTES: number;
+export declare const SNAPSHOT_IO_DEFAULT_MAX_TARGETS = 32;
+export declare const SNAPSHOT_IO_HARD_MAX_FILE_BYTES: number;
+/** Four schema-sized snapshots plus base64 and journal metadata fit below this ceiling. */
+export declare const SNAPSHOT_IO_HARD_MAX_JOURNAL_BYTES: number;
+export declare const SNAPSHOT_IO_HARD_MAX_TARGETS = 128;
+export declare const SNAPSHOT_IO_MAX_RELATIVE_NAME_BYTES = 256;
+export type SnapshotText = string | Uint8Array | null;
+export type SnapshotIoStep = "before-temp-write" | "after-temp-write" | "after-file-fsync" | "after-rename" | "after-directory-fsync" | "before-journal-remove" | "after-journal-remove" | "before-delete" | "after-delete";
+export interface SnapshotIoStepContext {
+    readonly step: SnapshotIoStep;
+    readonly phase: "journal" | "target";
+    readonly path: string;
+    readonly target: string | null;
+}
+/** Test seams are synchronous so a test can fail an exact persistence prefix without sleeps. */
+export interface SnapshotJournalHooks {
+    readonly now?: () => number;
+    readonly nonce?: () => string;
+    /** Called before an fd-backed read; useful for deterministic EIO/EACCES simulations. */
+    readonly beforeRead?: (path: string) => void;
+    /** Called after fstat on the opened descriptor, for growth/swap regression tests. */
+    readonly afterOpenRead?: (path: string) => void;
+    /** Called immediately before directory fsync. Throw an error with `code` to simulate it. */
+    readonly beforeDirectoryFsync?: (path: string) => void;
+    readonly beforeStep?: (context: SnapshotIoStepContext) => void;
+    readonly afterStep?: (context: SnapshotIoStepContext) => void;
+}
+export interface SnapshotJournalIoOptions {
+    /**
+     * Explicit trusted root. Its parent must not concurrently replace it with a same-user
+     * controlled path; race-proof containment against such an actor is out of scope.
+     */
+    readonly rootDir: string;
+    /** Exact flat, portable direct-child names this instance may replace or read. */
+    readonly targets?: readonly string[];
+    /**
+     * Optional bounded namespace policy for additional flat direct-child names.
+     * The predicate is never called for unsafe names; exceptions reject the name.
+     */
+    readonly acceptTarget?: (name: string) => boolean;
+    /** Flat, portable direct-child journal filename. */
+    readonly journalName?: string;
+    readonly maxFileBytes?: number;
+    readonly maxJournalBytes?: number;
+    readonly maxTargets?: number;
+    readonly hooks?: SnapshotJournalHooks;
+}
+export interface SnapshotReadOptions {
+    readonly maxBytes?: number;
+    /** When parsing reveals a corrupt or oversize target, quarantine it before returning. */
+    readonly quarantineCorrupt?: boolean;
+}
+export type SnapshotReadStatus = "ok" | "missing" | "oversize" | "corrupt" | "invalid-target" | "failed";
+export interface SnapshotReadResult<T> {
+    readonly status: SnapshotReadStatus;
+    readonly value: T | null;
+    readonly error: string | null;
+    readonly quarantinedPath: string | null;
+}
+export type SnapshotMutationStatus = "committed" | "recovered" | "none" | "recovery-loss" | "invalid" | "failed";
+export interface SnapshotMutationResult {
+    readonly status: SnapshotMutationStatus;
+    readonly transactionId: string | null;
+    /** A corrupt journal was quarantined. Existing targets are only a lower bound. */
+    readonly lowerBoundLoss: boolean;
+    readonly error: string | null;
+    readonly quarantinedPath: string | null;
+    /** Failed writes preserve the journal, so retrying commit/recover is safe. */
+    readonly retryable: boolean;
+}
+export interface SnapshotQuarantineResult {
+    readonly status: "quarantined" | "missing" | "invalid-target" | "failed";
+    readonly path: string | null;
+    readonly error: string | null;
+}
+export interface SnapshotWriterResult {
+    readonly status: "acquired" | "released" | "closed" | "busy" | "invalid" | "failed";
+    readonly error: string | null;
+    readonly retryable: boolean;
+}
+export interface SnapshotJournalIo {
+    readonly rootDir: string | null;
+    readonly journalPath: string | null;
+    readonly targetNames: readonly string[];
+    /** Effective bounded limits after defaults and hard-ceiling clamps. */
+    readonly maxFileBytes: number | null;
+    readonly maxJournalBytes: number | null;
+    readonly maxTargets: number | null;
+    readText(name: string, options?: SnapshotReadOptions): SnapshotReadResult<string>;
+    readJson<T = unknown>(name: string, validate?: (value: unknown) => value is T, options?: SnapshotReadOptions): SnapshotReadResult<T>;
+    quarantineTarget(name: string): SnapshotQuarantineResult;
+    /**
+     * Retain in-process root-scoped writer ownership across several recover/commit calls.
+     * Cross-process concurrent writers are unsupported.
+     */
+    acquireWriter(): SnapshotWriterResult;
+    releaseWriter(): SnapshotWriterResult;
+    close(): SnapshotWriterResult;
+    /** Recover any durable journal. A missing journal is a successful no-op. */
+    recover(): SnapshotMutationResult;
+    /** A null snapshot is an explicit tombstone for that target. */
+    commit(snapshots: Readonly<Record<string, SnapshotText>>): SnapshotMutationResult;
+}
+/** Construction is total: malformed runtime options turn later calls into explicit invalid results. */
+export declare function createSnapshotJournalIo(options: SnapshotJournalIoOptions): SnapshotJournalIo;