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.