# vera-session-tools

## Purpose
Provide session-scoped Vera orchestration plus lightweight Vera-specific interaction surfaces: `ask_user` panels, session todos, top-level Vera status, output guarding, prompt assembly, compaction, and time prompt augmentation.

## Non-goals
- web search, docs lookup, academic search, or PDF parsing; network retrieval belongs to `vera-web-tools`
- local workspace search binaries
- global banner/status-line/thinking chrome, which belongs to `vera-theme`
- provider compatibility shims such as `proxy-compat` or `rtk-rewrite`

## Registered surface

### Tools
- `ask_user`
- `todo`
- `check_vera`
- `time`

### Commands
- `/vera` — user-facing top-level Vera runtime status, including compaction routing, subagent runtime state, CCC readiness, and Scheme sandbox status

### Hooks
- `tool_result` — output truncation via `output-guard`
- `before_agent_start` — prompt-rules layering + system time injection
- `session_before_compact` — custom compaction pipeline
- `session_start` / `session_switch` — config and session override hydration
- `agent_end` — completion/notification sound via `notify-sound`

### Included extensions
- `ask-user`
- `todo`
- `check-vera`
- `output-guard`
- `compaction`
- `prompt-rules`
- `read-cap`
- `conditional-rules`
- `system-env`
- `skill-catalog`
- `time`
- `notify-sound`

## Config
- `agent/config/output-guard.json`
- `agent/config/compaction.json`
- project `.pi/config/output-guard.json`
- project `.pi/config/compaction.json`
- `agent/rules/SOUL.md` and project `.pi/rules/SOUL.md` for prompt layering

## External dependencies
- no separate API keys beyond the model/provider auth Pi already uses
- compaction depends on at least one available model in the active Pi registry
- compatibility patches for unusual providers now live in `agent/extensions/`, not this package

## Smoke
- `npm run smoke`
- `npm run smoke:offline`
- `npm run smoke:strict-network`
- from project root: `node scripts/smoke-all.mjs`

## Debugging
1. For manual inspection inside Pi, run `/vera`.
2. For agent/internal inspection, run `check_vera` to get package presence, compaction routing, memory status, subagent runtime status, CCC availability/project readiness, Scheme sandbox availability/integrity, config files, compat shims, web-tool readiness, and overall status (`ok` / `partial` / `degraded`).
3. Run `npm run smoke:offline` next; it covers registration, prompt layering, truncation, compaction wiring, and failure paths.
4. If prompt assembly is wrong, inspect `agent/rules/SOUL.md`, project `.pi/rules/SOUL.md`, and `@include` chains.
5. If output truncation is surprising, inspect `output-guard.json` and emitted `details.outputGuard` metadata.
6. If built-in `/compact` behaves oddly, inspect `/vera` first, then `agent/config/compaction.json` and any persisted `vera.compaction.override` session entries.

Loaded through `agent/settings.json` as `./packages/vera-session-tools`.