@aikaara/pikaara 0.0.1

package/README.md

@@ -0,0 +1,118 @@
+# pikaara
+
+Jev-centric coding-agent harness. Design source: `Coding_harness_plan/Jev-Engineering-for-Coding-Agents.pdf`.
+
+## Install
+
+```bash
+npm install -g @aikaara/pikaara   # Node >= 22.19; installs the `pikaara` command
+pikaara --version
+pikaara                  # interactive; `pikaara -p "<prompt>"` for one-shot
+```
+
+## Layout (npm workspaces, `@pikaara/*`)
+
+| Package | Paper section | Role |
+|---|---|---|
+| `jev` | I.A, Table I | Decision-layer contract: typed questions → choice / ranked / score / noul + probability; `withFallback` |
+| `classify` | I.A, Fig. 1 | **Core.** Our TypeSafe System One client (native, OpenRouter, Cloudflare) and the classifier Jev that answers every decision point, batching same-tick questions into one request |
+| `state` | Fig. 1 | Addressable, typed chunk store. Supersede, never delete; `onChange`/`restore` for persistence |
+| `durable` | II.E (restarts), VI.A | Our port of pi-durable: global IDs, atomic seq-numbered commits, chunks alive over `[createdAt, retiredAt)` (history + fork-aware reads), memory / crash-safe JSONL / SQLite (`node:sqlite`, WAL) storage, op-by-op documents (`diff`/`apply`, history at any seq), crash-resumable `TaskScheduler`, serialized `Session`, storage conformance suite (`@pikaara/durable/testing`) |
+| `context` | V, VIII | Visibility ladder per query; conditional instructions |
+| `tools` | IV.B, VII | Tiered disclosure (snippet / schema / docs); intent → tool routing |
+| `permissions` | IV.A | Programmable allow / ask / deny policies |
+| `router` | II.A, IX | Cost per context rebuild; data-sensitivity routing |
+| `runtime` | Fig. 1 | The loop wiring all of the above |
+| `ai` | Fig. 1 (LLMs) | pi-ai adapters: any-provider `ModelClient`, `discover()` (auth + subscription checks → `ModelInfo`), locked `FileCredentialStore` (`~/.pikaara/auth.json`), `createJev(spec)` (credential glue for classify) |
+| `swarm` | VI, VI.A, VI.B, X | Sub-agents: `task` tool, Jev-built per-goal context + toolsets, goal dedup (exact + Jev `duplicate`), per-path RW locks + write-claim admission, durable `TaskScheduler` tasks |
+| `coding-agent` | — | `pikaara` CLI: interactive TUI (pi-tui) + print mode, built-in tools (read/bash/edit/write/grep/find/ls, ported from pi), system prompt + AGENTS.md/CLAUDE.md discovery |
+
+Dependency direction: `durable` standalone; `jev` ← `classify`; `jev` ← `state` ← `context`; `jev` ← `tools|permissions|router`; all ← `runtime` ← `ai` ← `coding-agent`. External: `@earendil-works/pi-ai` (npm, pinned). No cycles (`scripts/build.mjs` enforces).
+
+## Rules
+
+- ESM, TS 7, `erasableSyntaxOnly`: no enums, namespaces, or constructor parameter properties.
+- Relative imports use `.ts` extensions (rewritten on build).
+- Workspace imports resolve to `src/` via the `source` export condition (typecheck, vitest, `npm run dev`); builds use `dist/`.
+- Every decision the harness makes per turn is a `jev.ask(point, input)` with a typed answer — don't branch on prose.
+- Format: tabs, width 120 (biome). Run `npm run check` before committing.
+
+## Jev (core)
+
+- Every per-turn decision (context visibility, cache, routing, tools, permissions, security) is a `jev.ask()` answered by the classifier Jev in `@pikaara/classify` — never pi-ai's classify.
+- Model is user-chosen: `--jev <provider/model>` or `PIKAARA_JEV`; default `typesafe/jev-latest`. Hosts: `typesafe` (TYPESAFE_API_KEY / `pikaara login typesafe`), `openrouter` (key or OAuth), `cloudflare-workers-ai`.
+- `pikaara jev` shows the active config; `pikaara jev set [provider/model] [--base-url]` saves it to `~/.pikaara/settings.json` for all sessions (interactive without args; prompts for a TypeSafe key if missing); `pikaara jev test` probes it; `pikaara jev reset`. Precedence: `--jev` > `PIKAARA_JEV` > settings > default.
+- On Jev failure the agent falls back to the rule baseline per decision and warns once.
+
+## Using pikaara
+
+- `pikaara` (TTY) opens the interactive agent; `pikaara "<prompt>"` / `pikaara -p "<prompt>"` runs once and prints (`--yes` auto-approves). `-c` resumes, `-m provider/id` pins the brain, `-j` picks Jev.
+- Keys: enter submit · shift+enter newline · esc interrupt · ctrl+c clear, twice to exit · ctrl+d exit · ctrl+o expand tool output · ↑ history.
+- Commands: `/model [id|auto]`, `/jev`, `/session`, `/new`, `/help`, `/quit`; `!cmd` runs a shell command yourself (output enters context).
+- Approvals: writes outside the repo and commands no rule/Jev clears are asked inline (Yes / Yes for session / No). Secrets (`~/.ssh`, `.env*`) are denied.
+- The current request's own chunks are always shown in full; Jev decides visibility for older ones.
+- `PIKAARA_DEBUG_FILE=path` appends every model request (JSON) for debugging.
+
+## Jev coverage of the paper (all rows implemented)
+
+- Prompt caching is on by default (`PIKAARA_CACHE=none|short|long`). The system prompt, tools and one content block per chunk form a stable prefix: Jev decides reuse vs rebuild once per request, later turns keep every earlier chunk's visibility, and the disclosed tool set is fixed per request. Measured on a 6-turn task: 49.9k of 58k prompt tokens served from cache, cost −71%. Print mode reports `cache read/write` on stderr; the footer shows `R…`.
+- Brain: default `auto` — Jev routes each turn across your subscription models and paid frontier models from gateways (OpenRouter; labs behind a gateway count as `vetted`, underlying vendor used). The shortlist keeps the best flat-rate and cheapest metered model per tier (frontier/mid/small); Jev sees cost + tier. `/model <id>` pins, `/model auto` restores.
+- Routing: models narrowed by data sensitivity (file rules ∪ Jev security score; settings `routing.sensitivity` / `routing.excludeVendors`), then Jev picks with per-candidate turn cost (`turnCost`: rebuild + generation).
+- `act` (paper IV.B): the model states an intent; Jev picks the tool, a small helper model (subscription haiku or cheapest capable; `brain.helper`) builds arguments from a tiny context, Jev fills enum/boolean fields as typed choices, schema validation with one repair round.
+- Headroom (XI): large chunks shown compressed are checked by Jev (`sufficient`); if facts the query needs were lost, the next rung is shown.
+- Micro-worlds (X): `simulate` dry-runs a command in a copy-on-write clone of the repo and reports created/modified/deleted files.
+- Evals (X): every request is recorded in `evals.jsonl`; `background.shadowModel` mirrors the final turn to a candidate model and Jev (`equivalent`) judges it — `/evals`, `pikaara evals`.
+- Tools: core tools always carry schemas; Jev discloses a few more per request; `load_tools` reaches the rest. Args are schema-validated; unknown tool names are routed by Jev to the right tool.
+- Ladder: large chunks get summaries at creation; `long` shows query-relevant lines (heatmap) when they exist.
+- Permissions: scripts a command runs (`python x.py`, `./x.sh`) are read before policy/Jev decide.
+- Conditional instructions: subdirectory AGENTS.md/FOOTGUNS.md and `.pikaara/instructions/*.md` (frontmatter `paths`/`keywords`) load only when relevant; skills (`.pikaara/skills/<name>/SKILL.md`, `~/.pikaara/skills`, built-in `eli5`) attach/detach with conditions and may add `allow` globs while active.
+- Variables: `vars` tool, durable per-conversation document, pinned each turn.
+- Background: shared retrieval per request (grep + identifiers + Jev), `/review` and `background.review` cross-model review, live `progress.html`, token accounting (`/stats`, `pikaara stats`).
+- Batteries: `outline` (symbols / one symbol's body), `ast_grep` (if installed), repetitive-output compression in `bash`, frequency-ranked `find`.
+
+## Benchmarks
+
+- `npm run bundle` → `dist-bundle/pikaara.mjs` (single file, Node ≥ 22.19).
+- Terminal-Bench via Harbor: `bench/terminal-bench/run.sh` (adapter `bench/terminal-bench/pikaara_agent.py`); needs Docker or `-e modal`.
+
+## Sub-agents and CLI tools
+
+- The main agent has a `task` tool: many subgoals at once, each a durable sub-agent with context selected by Jev from the parent's chunks and a Jev-ranked toolset. `access: "read"` (default) never contends and gets a read-only command policy; `access: "write"` + `files` claims serialize only overlapping edits (undeclared writes serialize with all writes). File tools take per-path read/write locks. Duplicate goals reuse earlier results. Sub-agents can't spawn sub-agents; approvals are queued one at a time.
+- Concurrency: `PIKAARA_SUBAGENTS` or `settings.json` `subagents.concurrency` (default 8), cap `subagents.maxTasks` (default 500). Unfinished sub-agents from a previous process are aborted (resumed with `-c`).
+- Any installed CLI is usable: `cli_search` (PATH discovery, Jev-ranked) → `cli_help` (--help/man on demand) → `bash`.
+- Permissions: `settings.json` `permissions.{allow,ask,deny}` globs over the whole command (deny > ask > allow, before defaults). The approval prompt's "Always allow" saves the exact command there.
+
+## Telemetry
+
+- Every run appends JSONL events to `~/.pikaara/sessions/<dir>/telemetry.jsonl` (`PIKAARA_TELEMETRY_FILE` overrides, `PIKAARA_TELEMETRY=0` disables): Jev decisions per turn, model calls (duration, tokens, cache, cost), tool calls (duration, ok, preview), permissions, fan-out/verify, background joins, sub-agent lifecycle.
+- `pikaara telemetry [paths] [-o report.html] [--open]` renders a self-contained dashboard (sessions and Terminal-Bench job dirs): stat tiles, per-task table, per-task timeline (model/tool/sub-agent lanes with hover detail), Jev decisions per turn, event log, tool usage, cost per task, token mix. `--trace` / `watch.py` give the live view.
+
+## Sessions
+
+- Every run persists its chunk store to `~/.pikaara/sessions/<dir>-<hash>/session.db` (SQLite; `main.jsonl` with `PIKAARA_STORAGE=jsonl`) (one commit per chunk change). `pikaara -c "<prompt>"` resumes the latest session for the cwd.
+
+## Auth
+
+- `pikaara login [provider] [--api-key]` — OAuth by default where offered; credentials in `~/.pikaara/auth.json` (0600, file-locked; `PIKAARA_DIR` overrides).
+- `pikaara auth [--all] [--refresh]` — per-provider status; `*` = subscription OAuth.
+- Subscription-backed models (Claude Pro/Max, ChatGPT Codex, Copilot, ...) have `subscription: true`; the router prices them at 0 marginal cost.
+- Env keys are used only when no credential is stored for that provider.
+
+## Dev
+
+- `.env` (gitignored; template `.env.example`) is loaded only by dev scripts. `LOCAL_<NAME>` maps to `<NAME>` (`scripts/dev-env.mjs`); with an OpenRouter key Jev defaults to `openrouter/typesafe/jev-1.13`.
+- Sessions are stored in SQLite (`session.db`) by default; `PIKAARA_STORAGE=jsonl` switches to JSONL. Legacy JSONL-only session dirs stay on JSONL so `-c` still resumes them.
+
+## Commands
+
+- `npm run check` — biome + typecheck
+- `npm test` — vitest across all packages (against source)
+- `npm run build` — topological `tsc` builds
+- `npm run build:watch` — build, then `tsc --watch` every package
+- `npm run dev -- "<prompt>"` — run the CLI from source (`-m provider/id`, `--list-models`)
+- `npm run dev:watch -- "<prompt>"` — same, rerun on source change
+- `npm run dev:jev` — probe the configured Jev
+- `npm run link` — build + `npm link` the `pikaara` bin globally; `npm run dev:link` = link + watch build (global `pikaara` picks up every rebuild); `npm run unlink`
+- `npm run bench -- [harbor args]` — Terminal-Bench run with a realtime dashboard URL; `npm run bench:dashboard` to attach; `npm run bench:report` compares runs
+- `npm run pack:npm` — bundle + assemble the publishable `@aikaara/pikaara` package in `dist-npm/`. Publishing: push a `vX.Y.Z` tag (or run the "npm publish" workflow; dry run by default) → `.github/workflows/npm-publish.yml` lints, tests, bundles, installs it globally on Linux/macOS/Windows and publishes with provenance (secret `NPM_TOKEN` or npm trusted publishing)
+- `node scripts/new-package.mjs <dir> "<desc>" [deps...]` — scaffold a package

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@aikaara/pikaara",
+	"version": "0.0.1",
+	"description": "pikaara: aikaara coding agent — a Jev-centric harness",
+	"keywords": [
+		"pikaara",
+		"coding-agent",
+		"ai",
+		"agent",
+		"cli",
+		"llm",
+		"jev",
+		"terminal",
+		"aikaara"
+	],
+	"license": "ISC",
+	"author": "vinayak iyer (vinayak@aikaara.com)",
+	"homepage": "https://github.com/aikaara/pikaara#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/aikaara/pikaara.git"
+	},
+	"bugs": {
+		"url": "https://github.com/aikaara/pikaara/issues"
+	},
+	"type": "module",
+	"bin": {
+		"pikaara": "pikaara.mjs"
+	},
+	"files": [
+		"pikaara.mjs",
+		"native",
+		"README.md",
+		"LICENSE",
+		"LICENSE.md"
+	],
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}