agentera 0.0.0 → 3.0.0-dev.1

package/README.md

@@ -1,48 +1,9 @@
-# agentera (npm)
+# Agentera CLI (v3)
 
-Placeholder npm package that reserves the [`agentera`](https://www.npmjs.com/package/agentera) name for `npx agentera` ahead of the Agentera 3.0 TypeScript CLI.
+Placeholder for the planned TypeScript CLI rewrite.
 
-**0.x** releases are a thin Node shim. **3.0.0** will ship the native Bun/npm CLI described in the main repository.
+The current Python CLI lives at `scripts/agentera` in the repository root.
+This package will eventually host the v3 TypeScript implementation.
 
-## Usage
-
-```bash
-npx agentera --version
-npx agentera prime
-npm install -g agentera
-```
-
-## Delegation order
-
-When you run `agentera`, the shim forwards to the existing Python CLI using the first match:
-
-1. **Installed app-home** — `$AGENTERA_HOME/app/scripts/agentera` via `uv run`
-2. **Repository checkout** — nearest parent directory containing `scripts/agentera`, via `uv run scripts/agentera`
-3. **`uvx` from GitHub** — `uvx --from git+https://github.com/jgabor/agentera@<tag> agentera` (tag pinned in `package.json` → `agentera.gitRef`)
-4. **Install help** — stderr guidance and exit code 1 if nothing above applies
-
-The shim does not bundle Python, skills, or hooks. Install paths for runtimes remain in the [main README](https://github.com/jgabor/agentera#get-started).
-
-## Publishing (maintainers)
-
-From this directory after review:
-
-```bash
-npm pack
-npm publish --access public
-```
-
-Verify from a clean directory:
-
-```bash
-npx agentera@0.0.0 --version
-```
-
-## Development
-
-```bash
-node packages/cli/bin/agentera.mjs --version
-node packages/cli/bin/agentera.mjs --help
-```
-
-Suite version pin lives in `package.json` under `agentera.suiteVersion` / `agentera.gitRef`; npm `version` stays on the `0.0.x` line until 3.0.
+See the [Agentera repository](https://github.com/jgabor/agentera) for the
+current CLI documentation and usage.

package/bundle/.agentera-npx-bundle.json

@@ -0,0 +1,4 @@
+{
+  "kind": "agentera-npx-bundle",
+  "suiteVersion": "2.7.6"
+}

package/bundle/references/adapters/cursor.md

@@ -0,0 +1,213 @@
+# Cursor adapter reference
+
+Agentera v1 ships Cursor as two registry identities:
+
+| Identity | Host | Support status |
+| -------- | ---- | -------------- |
+| `cursor` | Cursor IDE (Composer / Agent) | supported |
+| `cursor-agent` | Cursor Agent CLI (`cursor-agent`, `agent`) | degraded |
+
+Decision 63 owns v1 scope. Cloud agents are unsupported. Bare text `hej` routing
+stays metadata-only like Claude, Copilot, and Codex.
+
+## Quick install
+
+**Local plugin (no Marketplace listing required)**
+
+```bash
+git clone https://github.com/jgabor/agentera.git ~/.cursor/plugins/local/agentera
+# or: ln -s /path/to/agentera ~/.cursor/plugins/local/agentera
+```
+
+Restart Cursor or run **Developer: Reload Window**. The plugin root must contain
+`.cursor-plugin/plugin.json`. Agentera is not published to the Cursor Marketplace
+yet; use this manual local path or Cursor's local plugin loading UI instead.
+
+The plugin loads skills, managed capability agents, and plugin hooks. When you open
+a project that is not an Agentera install root, `sessionStart` exports
+`AGENTERA_HOME` from the plugin checkout (including a plugin-root fallback when env
+and project walk-up do not resolve a managed root).
+
+**Portable skill plus project upgrade**
+
+```bash
+npx skills add jgabor/agentera -g -a cursor --skill agentera -y
+uvx --from git+https://github.com/jgabor/agentera agentera upgrade --project "$PWD" --runtime cursor --yes
+uvx --from git+https://github.com/jgabor/agentera agentera doctor --runtime cursor
+```
+
+Use the plugin path for a user-global install. Use upgrade when you need
+project-committed `.cursor/hooks.json` and `.cursor/agents/` copies. Both paths can
+be combined.
+
+From a clone, replace `uvx … agentera` with `uv run scripts/agentera`. User-facing
+install steps also live in [`README.md`](../../README.md) and
+[`UPGRADE.md`](../../UPGRADE.md).
+
+## Repo-native surfaces
+
+This repository dogfoods committed Cursor surfaces:
+
+- `.cursor/hooks.json` — sessionStart env export, preToolUse hard gate, postToolUse advisory validation
+- `.cursor/agents/*.md` — twelve managed capability descriptors
+- `.cursor-plugin/plugin.json` — marketplace submission-ready manifest
+
+Hooks resolve helper scripts through `uv run hooks/...` from the project root.
+`sessionStart` exports `AGENTERA_HOME` through Cursor hook JSON (`env`) before
+subsequent hook executions run.
+
+## AGENTERA_HOME wiring
+
+Primary path: `hooks/cursor_session_start.py` resolves the install root from
+`AGENTERA_HOME`, project walk-up, or the plugin/checkout root (`hooks/` parent)
+when the hook runs from a plugin install, then returns
+`{"env": {"AGENTERA_HOME": "<root>"}}` plus optional `additional_context` from
+the shared session digest.
+
+Fallback: `scripts/setup_cursor.py` reports persistent shell configuration only
+when live shell-tool smoke proves session env does not propagate to CLI
+subprocesses. Agentera does not write shell rc files by default.
+
+## Artifact validation
+
+| Surface | Behavior | Claim status |
+| ------- | -------- | ------------ |
+| IDE `preToolUse` (Write/Edit) | Deny invalid reconstructable artifact candidates | Verified after live preToolUse Write smoke (2026-05-24) |
+| IDE `postToolUse` (Write/Edit) | Advisory validation through shared `validate_artifact.py` | Active |
+| CLI | Degraded; depends on workspace hook install and env propagation | Follows IDE smoke evidence only |
+
+Live preToolUse Write smoke passed on 2026-05-24 with invalid-block and valid-allow
+cases recorded in `.agentera/smoke-cursor-pretooluse-evidence.txt`. Conditional
+hard-gate claims for reconstructable IDE Write and Edit candidates are verified;
+release tagging and marketplace publication remain blocked pending broader release
+closeout.
+
+## Subagent dispatch
+
+IDE: managed descriptors under `.cursor/agents/` with `<!-- agentera: managed -->`
+ownership markers. Upgrade refreshes Agentera-owned targets and preserves unknown
+collisions.
+
+CLI: host-managed `cursor-agent` print mode; no separate TOML descriptor install.
+Eval coverage targets `cursor-agent` first.
+
+## Upgrade and doctor
+
+```bash
+uv run scripts/agentera upgrade --runtime cursor --dry-run
+uv run scripts/agentera doctor --runtime cursor
+```
+
+Upgrade copies managed hooks, agents, and plugin metadata into target projects
+with the same ownership protections used for OpenCode and Codex.
+
+Doctor reports helper access, hook presence, and managed agent alignment.
+
+## Eval
+
+```bash
+uv run scripts/eval_skills.py --runtime cursor-agent --skill hej --dry-run
+```
+
+Print mode uses `cursor-agent -p --output-format json --force`. Harnesses apply
+bounded timeouts because some CLI builds hang after completion.
+
+## Unsupported in v1
+
+- Cloud agents (no project hook or managed-agent guarantees)
+- Bare `hej` prompt rewrite routing
+- Session compaction injection beyond shared hook helpers
+- Separate cursor-agent hook install distinct from IDE workspace surfaces
+
+## Profilera session corpus (Section 22)
+
+Profilera mines five canonical record types from host session data. This section
+maps each record type to Cursor IDE local storage on disk.
+
+### Probe paths
+
+| Path | Purpose |
+| ---- | ------- |
+| `~/.cursor/projects/` | Root directory for workspace-scoped Cursor state |
+| `~/.cursor/projects/<project-slug>/agent-transcripts/<session-id>/*.jsonl` | Agent session transcripts (Composer / Agent) |
+| `~/.cursor/projects/<project-slug>/repo.json` | Workspace metadata (`id` UUID); slug mapping is primary for project scoping |
+| `~/.config/cursor/chats/<md5(project-path)>/<session-id>/store.db` | Cursor Agent CLI chat store (gap-fill when JSONL absent) |
+
+Override the projects root with `--cursor-projects-dir`, the CLI chats root with
+`--cursor-chats-dir`, or disable both Cursor runtimes with `--no-cursor` on
+`scripts/extract_corpus.py` and `agentera stats refresh`.
+
+Project slug convention: absolute project path segments joined with `-`, lowercased
+(for example `/home/user/git/agentera` → `home-user-git-agentera`). CLI workspace
+hashes use `md5(absolute-project-path)` hex (same string Cursor uses under
+`~/.config/cursor/chats/`). When `--project-root` is supplied, extraction prefers
+matching slugs and workspace hashes over unrelated stores.
+
+### Transcript JSONL shape
+
+Each line is a JSON object:
+
+```json
+{"role": "user", "message": {"content": [{"type": "text", "text": "..."}]}}
+{"role": "assistant", "message": {"content": [{"type": "text", "text": "..."}, {"type": "tool_use", "name": "grep", "input": {"pattern": "..."}}]}}
+```
+
+Roles are `user` or `assistant`. `message.content` is a list of blocks. Text blocks
+use `type: "text"`. Tool blocks use `type: "tool_use"` with `name` and `input`.
+
+### Cursor Agent CLI `store.db` shape
+
+Runtime id `cursor-agent` reads SQLite stores at
+`~/.config/cursor/chats/<workspace-hash>/<session-id>/store.db`. Each store has:
+
+| Table | Purpose |
+| ----- | ------- |
+| `blobs` | JSON message payloads keyed by content hash (`role`, `content`, optional tool blocks) |
+| `meta` | Session metadata (`agentId`, model, mode) |
+
+JSON blobs use `role` values such as `user`, `assistant`, and `tool`. User content is
+often a plain string; assistant content is a list that may include `text` and
+`tool-call` items (`toolName`, `args`). Sessions that already have IDE JSONL under
+`agent-transcripts/<same-session-id>/` are skipped (gap-fill only).
+
+### Portable record families
+
+| Family | Cursor source | Status |
+| ------ | ------------- | ------ |
+| Decision history | `history_prompt` from decision-rich user text blocks | Yes (local JSONL) |
+| Conversation exchanges | `conversation_turn` from user/assistant lines | Yes (local JSONL) |
+| Tool usage | `tool_call` from `tool_use` / `tool-call` blocks | Yes (bounded args) |
+| Instruction documents | Project `AGENTS.md` via shared `--project-root` scan | Yes (filesystem) |
+| Project config signals | Project manifests via shared `--project-root` scan | Yes (filesystem) |
+
+### Degradation and privacy
+
+Extraction is read-only and local-only. Runtime status uses the shared
+`runtime_statuses` vocabulary (`ok`, `missing`, `sparse`, `degraded`, `skipped`).
+Diagnostics report counts and bounded reasons only; raw transcript text must not
+appear in errors, smoke output, or test assertions.
+
+| Condition | Status | Reason |
+| --------- | ------ | ------ |
+| Store path disabled (`--no-cursor`) | `skipped` | `disabled` |
+| `~/.cursor/projects` or `~/.config/cursor/chats` absent | `missing` | `store_absent` |
+| No `*.jsonl` under `agent-transcripts` / no gap-fill `store.db` | `sparse` | `no_candidate_files` / `no_matching_records` |
+| Permission denied | `degraded` | `store_locked` |
+| Invalid JSONL lines | `degraded` | `schema_divergent` |
+| Candidates present but no normalized records | `sparse` | `no_matching_records` |
+
+### Gaps
+
+- Numeric or opaque project directory names (no slug) skip filesystem project-path
+  inference; `--project-root` mapping still scopes extraction when the slug matches.
+- Cloud agent sessions do not write local `agent-transcripts` in v1.
+- `cursor-agent` `store.db` sessions that already have IDE JSONL transcripts are skipped
+  to avoid duplicate corpus records; gap-fill covers chat-only CLI sessions.
+- Binary or non-JSON blobs in `store.db` degrade with bounded diagnostics and do not
+  leak transcript text.
+
+## Source of truth
+
+RuntimeAdapter records live in
+`references/adapters/runtime-adapter-registry.yaml`. Parity comparisons belong in
+`references/adapters/runtime-feature-parity.md`.