audacity-cli 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+Audacity Investments CLI License
+
+Copyright (c) 2026 Audacity Investments. All rights reserved.
+
+This software is proprietary to Audacity Investments. Permission is granted
+to download, install, and use this software solely to access services
+provided by Audacity Investments, subject to your agreement with Audacity
+Investments.
+
+You may not modify, distribute, sublicense, or create derivative works of
+this software, in whole or in part, except as expressly permitted in
+writing by Audacity Investments.
+
+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
+AUDACITY INVESTMENTS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY
+ARISING FROM THE USE OF THE SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# audacity
+
+A local, Claude-Code-style CLI coding agent whose "brain" is **your own Audacity
+infrastructure** — never an external Claude/OpenAI endpoint. It talks only to the
+Audacity web host's OpenAI-compatible chat endpoints, authenticated with a personal
+`audacity_api_…` key.
+
+```
+audacity                      # interactive REPL
+audacity "fix the failing test"   # run one prompt to completion, then exit
+```
+
+## How it works
+
+- **Phase 1 — `/rag false` (default):** a full coding agent. Each turn streams from
+  `POST {AUDACITY_API_URL}/v1/chat/completions`, and the model can call local tools
+  (`read_file`, `list_files`, `grep`, `edit_file`, `write_file`, `run_bash`). The
+  conversation is held in memory and resent on every call (the endpoint is stateless).
+- **Phase 2 — `/rag true` (coming soon):** routes to `POST {AUDACITY_API_URL}/v1/agent/chat/completions`,
+  the Mastra RAG agent (server-side memory + company/fund/doc tools). Same key, same
+  wire format. The `/rag true` slash command already toggles session state; sending in
+  RAG mode currently prints a "Phase 2" notice.
+
+All transport/auth lives in `src/model.ts` (the only integration seam). The public web
+host handles the litellm-proxy JWT and Cloud Run IAM downstream — the CLI only ever
+sends your `audacity_api_…` key. No `gcloud`, no service token.
+
+## Setup
+
+```bash
+bun install
+bun run build          # → dist/index.js (executable, with shebang)
+```
+
+Run it:
+
+```bash
+bun run dev            # dev (bun --watch src/index.ts)
+node dist/index.js     # after build
+```
+
+### Install globally (recommended)
+
+```bash
+cd apps/audacity
+npm install -g .       # builds dist/ via the prepare hook, then links `audacity` onto your PATH
+audacity               # now works from any directory
+```
+
+`npm install -g .` runs the `prepare` script (`tsup`), so the self-contained
+`dist/index.js` is built at install time — no separate build step needed. (`bun link`
+or `npm link` also work for local development.)
+
+On first run, `audacity` prompts for your **production** key and a model, then saves
+them to `~/.audacity/config.json` — so it's remembered across every session, shell,
+and terminal on the machine. You only enter the key once.
+
+To unregister the local global install later:
+
+```bash
+npm uninstall -g audacity-cli   # removes the `audacity` command from your PATH
+```
+
+## Publishing to npm
+
+The package is **self-contained** — no `workspace:*` deps, only `commander` at runtime —
+so it publishes straight from `apps/audacity` with no monorepo build orchestration.
+
+> **You don't need to build first.** The `prepare` lifecycle script (`tsup && chmod +x`)
+> runs automatically on `npm publish`, so the shipped `dist/index.js` is always freshly
+> built from the current `src/`.
+
+**One-time setup:**
+
+```bash
+npm login                       # authenticate to the npm registry
+```
+
+**Publish:**
+
+```bash
+cd apps/audacity
+npm publish --dry-run           # inspect the tarball WITHOUT publishing — do this first
+npm publish                     # ships audacity-cli@<version> to the public registry
+```
+
+The dry run prints exactly what ships. Expect only three files —
+`dist/index.js`, `package.json`, `README.md` (controlled by the `files: ["dist"]`
+whitelist; `README.md` is always included automatically). No `src/`, no tests.
+
+After publishing, anyone can install it:
+
+```bash
+npm install -g audacity-cli
+audacity
+```
+
+> **Name note:** the package name is `audacity-cli` (the bare `audacity` name is taken
+> on npm). If you ever want to namespace it under the org instead, rename to a scoped
+> name like `@audacity-investments/cli` in `package.json` and publish with
+> `npm publish --access public` (scoped packages default to private otherwise).
+
+## Updating the published package
+
+You can **never** republish the same version number, and unpublishing is restricted
+(only within 72h). The fix for any bad release is always to **roll forward** — publish a
+higher version. Never delete; just bump.
+
+```bash
+cd apps/audacity
+npm version patch               # 0.1.0 → 0.1.1  (bug fixes)
+# npm version minor             # 0.1.1 → 0.2.0  (new features, backwards-compatible)
+# npm version major             # 0.2.0 → 1.0.0  (breaking changes)
+npm publish
+```
+
+`npm version` bumps `package.json` and creates a git commit + tag. Then `npm publish`
+rebuilds via `prepare` and ships the new version. Users upgrade with:
+
+```bash
+npm install -g audacity-cli@latest
+```
+
+While the version stays under `1.0.0`, semver convention treats every release as
+potentially breaking — fine for early development. Cut `1.0.0` once the wire format and
+CLI surface are stable.
+
+## Configuration
+
+`audacity` is **self-contained**: the only source of configuration is
+`~/.audacity/config.json`. It depends on no environment variables and nothing else on
+the machine — a key entered once is remembered globally on that device, across every
+shell, directory, and session.
+
+On first interactive run, `audacity` prompts for your production key (pasted, not
+echoed) and a model, defaults the base URL to **production**
+(`https://portal.audacityinvestments.com`), and **auto-saves** to
+`~/.audacity/config.json` (`chmod 600`) — no "save?" prompt. Requests go to the public
+prod host, which routes them through the production litellm-proxy downstream. Run `/key`
+anytime to change the saved key. One-shot mode (`audacity "…"`) never prompts — it reads
+the saved config and errors clearly if no key is saved.
+
+Optional field: **`compactModel`** — the model `/compact` uses to summarize. Summarizing
+is an easy task, so it defaults to a cheap, fast model (`gemini-2.5-flash`) independent of
+your chat model; set `compactModel` to override it.
+
+```json
+{
+  "apiUrl": "https://portal.audacityinvestments.com",
+  "apiKey": "audacity_api_…",
+  "model": "claude-opus-4-8",
+  "compactModel": "gemini-2.5-flash"
+}
+```
+
+## REPL commands
+
+| Command | Action |
+|---------|--------|
+| `/model [id]` | Pick a model (no arg → numbered picker; sourced from `apps/litellm/litellm_config.yaml`) |
+| `/rag true\|false` | Toggle RAG mode for the session (Phase 2 for `true`) |
+| `/auto` | Toggle auto-approve for mutating tools |
+| `/key` | Re-enter and save your API key |
+| `/cwd` | Show the working directory |
+| `/compact` | Summarize older turns into one message, keep the last 2 verbatim (shrinks context) |
+| `/clear` | Reset the conversation |
+| `/exit` | Quit |
+
+## Permissions
+
+`read_file`, `list_files`, `grep` run without prompting. `edit_file`, `write_file`,
+`run_bash` ask for `y/N` approval first (showing exactly what will run) — bypass with
+the `--yes`/`-y` flag or the `/auto` toggle. In one-shot mode, mutating tools require
+`-y`.
+
+## Testing prompt caching
+
+The harness is a realistic way to exercise **OpenAI prompt caching**: it resends
+the whole conversation on every turn (the endpoint is stateless), so a large,
+stable prefix repeats call after call — exactly what the provider cache rewards.
+Cheaper cached input tokens are captured server-side as
+`litellm_usage_log.cached_input_tokens` (see `apps/litellm-proxy/README.md` for
+the full metering/verification story).
+
+### Prerequisites
+
+1. **Point at an environment where the capture is deployed.** Prompt-cache
+   metering lives on the **UAT** proxy first. Set `~/.audacity/config.json`:
+   ```json
+   {
+     "apiUrl": "https://web-uat-qpe5npob6a-uk.a.run.app",
+     "apiKey": "audacity_api_…your UAT key…",
+     "model": "gpt-5.5"
+   }
+   ```
+2. **Use an OpenAI model** (`gpt-5.5`, `gpt-5.4`, …). OpenAI caches
+   automatically; other providers need explicit cache markers that aren't wired
+   yet.
+
+### ⚠️ Cache population is asynchronous
+
+The cache isn't guaranteed warm on the very next turn — an early turn can still
+report `cached_tokens = 0`, and hits land reliably only after the prefix has been
+seen a few times. Run **several turns in one session** and don't `/clear`.
+
+### Good sessions to trigger hits
+
+Load a large file early (so the prefix crosses OpenAI's ~1024-token floor), then
+ask follow-ups that reuse that context:
+
+```
+read apps/litellm-proxy/src/routes/api/chat/completions/index.ts
+walk me through the streaming success path
+where exactly is user cost computed vs fmv cost?
+now explain the non-streaming path and how it differs
+```
+
+or a multi-file exploration:
+
+```
+read src/agent.ts, src/model.ts, and src/tools.ts
+explain how a tool call flows from the model back into the loop
+which tools require approval and where is that enforced?
+```
+
+**Bad** cache tests (expect `no cache`): short one-liners with no file context,
+`/clear` between questions, or jumping topics each turn.
+
+### Observe the hits
+
+The harness streams and doesn't print usage, so watch the proxy logs
+(the `stream` variant fires for harness traffic):
+
+```bash
+gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="litellm-proxy-uat" AND textPayload:"[DEV:prompt-cache]"' \
+  --project=audacity-uat --limit=10 --freshness=10m --format='value(textPayload)'
+```
+
+Expect `cached_input_tokens` to climb turn over turn, e.g.
+`[DEV:prompt-cache] stream model=gpt-5.5 prompt_tokens=4450 cached_input_tokens=4224 CACHE HIT`.
+
+## Test
+
+```bash
+bun test               # tool-layer unit tests (no API key needed)
+bun run typecheck
+```