@npmmo/roster 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roster 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,74 @@
+# Roster
+
+> **Your agent has 200 tools. Only five get to start.**
+
+Roster is a neutral, open-source, local-first **tool router** for AI agents. One MCP endpoint fronts your local stdio MCP servers and approved skills; your agent gets the best ≤5 tools for the task at hand — the starting five — instead of every schema at once. It learns from derived call outcomes on your machine and works with MCP clients that can launch a stdio server, including Claude Code, Codex, Cursor, and OpenClaw.
+
+**The eject promise, up front: `roster eject` restores every active path Roster synced for its four write clients**, from backups committed before each client write. Dedicated MCP config files return byte-for-byte (comments and formatting included). Live state files the client itself rewrites, such as `~/.claude.json`, restore key-level: original servers return, Roster's exact injected entry is removed, and settings or servers changed since sync survive. `--force` explicitly selects the pristine raw bytes. A private journal makes a multi-path eject recoverable after interruption, and topology checks refuse a moved symlink rather than writing through it.
+
+## Why
+
+Tool schemas can consume [72% of a 200K context window before the first user query](https://agentmarketcap.ai/blog/2026/04/08/mcp-context-bloat-enterprise-scale-tool-definitions-agent-context-budget). Tool-selection accuracy collapses [from 43% to ~13.6% as toolsets grow](https://writer.com/engineering/rag-mcp/). In a 100-server live stress test, [the median MCP server passed only 71% of tasks; the bottom decile passed 38%](https://www.digitalapplied.com/blog/mcp-server-reliability-100-server-stress-test-study). And the haystack keeps growing: [177,000+ public MCP tools as of February 2026](https://micheallanham.substack.com/p/ai-agents-2026-the-tool-selection).
+
+Search-based tool loading is a proven fix — Anthropic measured [an 85% token cut, with accuracy going 49% → 74%](https://www.anthropic.com/engineering/advanced-tool-use) — but shipped it for Claude. Roster's bet is that the fix should be **neutral** (every client), **learned** (outcomes, not just keywords), and **public** (a league, not a listicle).
+
+## What it is
+
+Four parts, one product:
+
+- **The router ("the Rotation").** An aggregating stdio MCP proxy for command-backed servers. Your supported write-client configs go from N `mcpServers` entries to one. Default mode is **transparent**: a faithful passthrough — every backend tool re-exported (namespaced), with titles, annotations, execution hints, and error codes preserved — while only derived outcomes are stored locally. Opt into **five mode** and the agent sees two meta-tools — `draft(need)` returns the best ≤5 capabilities for the stated task (K configurable 1–10), `call(tool, args)` proxies the invocation. When a drafted tool hard-fails, Roster can attach a structured suggestion for the next-ranked equivalent (the Sixth Man — suggest-only; Roster never executes the alternate).
+- **The Coach.** Local outcome learning. Outcome class, latency, hashes, and drift are stored on-device; raw prompts, arguments, and results are not. An opportunistic maintenance job refines routing toward the tools that work on *your* stack. No hosted Roster service or API key is involved.
+- **The League.** A static generator for public MCP server rankings, fed by the open-source Combine harness. Certification binds category, task signing, and descriptions to an exact authoritative suite/version; standings rank only within that identical comparison set. Named scores use `signedWilsonLb` only. Artifacts are validated before a complete atomic site swap, and box-score filenames include a SHA-256 identity suffix so lossy display names cannot collide. The committed run remains unsigned pre-season data until a human signing session occurs. See [docs/methodology.md](docs/methodology.md).
+- **The Playbook.** Skills (SKILL.md) are first-class alongside tools. Tree traversal and script reads are bounded and no-follow. A primary `SKILL.md` symlink is the deliberate exception for dotfile-managed installs: its descriptor is read with a bound and identity checks, it is always review-flagged, and it is withheld by default. Unreadable entries, unsupported file types, other symlinks, or scan-cap exhaustion likewise produce a review finding. Review-flagged skills become available only through the explicit `ROSTER_ALLOW_REVIEW_SKILLS=1` operator override.
+
+## Quickstart
+
+> **Initial CLI preview.** The package is `@npmmo/roster`; the installed executable remains `roster`. The unrelated unscoped `roster` package is not this project. Publication approval and release evidence are tracked in [release readiness](docs/release-readiness.md).
+
+```sh
+npm install --global @npmmo/roster
+roster init       # detect clients, import supported servers, print your Day-0 receipt
+roster sync       # swap N config entries for one (originals backed up first)
+roster serve      # run the router
+roster eject      # put every config back exactly as found (byte-for-byte for dedicated files)
+roster receipt    # re-print your audit  ·  roster unquarantine <id>  # re-admit a drift-benched tool
+```
+
+The published CLI supports Node **22.17 or newer within Node 22.x, or 24.2 or newer**. Older Windows/libuv builds cannot provide consistent file identities and are refused before local state is created; file-safety checks are not weakened to accommodate them. `init` needs no account or Roster API key. It prints a Day-0 receipt of clients, servers, and skills discovered, modeled per client: clients that already defer tool schemas natively, like Claude Code, are reported as such rather than credited with savings they do not need. `sync` currently writes Claude Code, Cursor, Codex, and OpenClaw configs and routes command-backed stdio servers only. If a selected config contains a URL-only server, unsupported server settings (such as client-specific disable/allowlist rules, `cwd`, or `env_vars`), or malformed server definitions, sync refuses before changing `roster.json`, backups, or the client config rather than silently discarding those settings. Explicit `command`, `args`, and string-valued `env` entries remain supported. If the client edits its config during sync preparation, sync refuses the observed conflict; retry when the client is idle.
+
+Synced launchers use this installation's absolute Node and CLI paths, or the scoped package command for an npx-cache install. Re-running sync migrates older recorded launchers without importing Roster into itself.
+
+## Seven day-one utilities
+
+The League is the show; these earn the install without it:
+
+1. **Context relief where you enable five mode** — best-five serving behind a stable two-tool interface, with transparent mode as the default.
+2. **One roster across the four write clients** — import command-backed servers from their different config formats, then point those clients at one local endpoint.
+3. **The Sixth Man** — failover *suggestions* when a tool hard-fails, so one bad server doesn't kill the task. Suggest-only at launch; automatic substitution returns later, if field data earns it.
+4. **The local outcome record** — derived outcome classes and latency support ratings and maintenance without persisting prompts, arguments, or results. The dashboard remains planned, not shipped.
+5. **Drift quarantine** — changed capability definitions are quarantined locally, including remove/re-add cases carried through tombstones.
+6. **Secrets hygiene** — API keys live in **one place** (`~/.roster/roster.json`, owner-only `0600`, alongside the config backups that hold your original files) and are passed through to backends only. They are never sent anywhere, never written to the outcome database, and never logged — but be clear-eyed: importing a server copies its `env` block, so those keys are on disk, exactly as they already were in each client's own config.
+7. **A Coach that learns your team** — local outcomes refine routing on your own stack; public-Lab prior seeding remains planned.
+
+## Privacy
+
+- **Local-first, by law.** No account or Roster API key. State lives in `~/.roster/`. Lexical full-text retrieval works with no model and no download, so the install is ~39 MB and Roster is useful the moment it finishes. Semantic (dense) retrieval is **opt-in**: `roster init` asks, or `roster dense enable` adds it later — it installs a ~385 MB local embedding runtime into `~/.roster/runtime` and then fetches a model from Hugging Face in the background on first use. Decline it, or stay permanently offline, and Roster runs in lexical mode forever. Nothing is uploaded either way.
+- **Your content never leaves.** Prompts, tool arguments, and results are never uploaded, persisted to the outcome database, or logged.
+- **Telemetry is OFF by default and opt-in only.** `roster telemetry status|on|off` controls it; the published schema in [docs/telemetry-schema.md](docs/telemetry-schema.md) defines exactly what could ever be sent — coarse outcome events only, with hard exclusions for prompts, args, results, embeddings, hostnames, and paths. Aggregates publish only past k-anonymity thresholds. Full schema: [docs/telemetry-schema.md](docs/telemetry-schema.md). The upload endpoint does not exist yet, so today nothing leaves your machine even if you opt in. Before launch, the OFF default gets verified by packet capture.
+
+## Status: initial CLI preview
+
+The CLI, the public League, and hosted surfaces have separate release gates. [Release readiness](docs/release-readiness.md) records the candidate evidence and remaining owner actions; passing repository tests is not a claim that every client or environment has been verified.
+
+- **Package identity:** `@npmmo/roster`, with executable `roster`. Every publication requires the reviewed artifact, public-registry verification, and owner approval. The earlier `@roster/cli` choice was not an owned publication namespace for the authenticated release account.
+- **League and hosted surfaces:** the League generator can build locally from the committed artifact, but named public scores remain gated on human-signed verifiers. Publishing the CLI does not publish the League, register a domain, or create a telemetry endpoint.
+- What exists today: a pnpm/TypeScript monorepo (`packages/router`, `coach`, `cli`, `combine`, `playbook`, `shared`) with CI, built against the milestones in [ROSTER-BUILD-HANDOFF.md](ROSTER-BUILD-HANDOFF.md). Strategy and decision records: [ROSTER.md](ROSTER.md), [ROSTER-STATE-AND-DECISIONS.md](ROSTER-STATE-AND-DECISIONS.md).
+- Day-to-day build status: [STATUS-FOR-MO.md](STATUS-FOR-MO.md) · design docs: [docs/](docs/).
+
+## Built with agents, reviewed by hand
+
+Roster is developed with heavy agentic AI assistance, under written discipline: specs are amended before code, security-critical paths (eject/config rewriting, credential passthrough, telemetry redaction) are committed to line-by-line human review before launch, and no named public score ever comes from a verifier a human didn't sign. The full disclosure, the rules, and the running human-review log live at [docs/PROVENANCE.md](docs/PROVENANCE.md).
+
+## License
+
+[MIT](LICENSE).