vera-session-tools

Purpose

Provide session-scoped Vera behavior that is neither UI-specific nor network-tool-specific: user prompts, session todos, top-level Vera diagnostics, output guarding, prompt assembly, compaction, and system-time prompt augmentation.

Non-goals

• web search, docs lookup, academic search, or PDF parsing
• local workspace search binaries
• banner/status-line/thinking shortcut UI
• provider compatibility shims such as proxy-compat or rtk-rewrite

Registered surface

Tools

• ask_user
• todo
• check_vera

Commands

• /vera_status — user-facing top-level Vera runtime status, including compaction routing, subagent/Chimera runtime state, and CCC readiness

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

Included extensions

• ask-user
• todo
• check-vera
• output-guard
• compaction
• prompt-rules
• system-time

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 agent/scripts/smoke-all.mjs

Debugging

1. For manual inspection inside Pi, run /vera_status.
2. For agent/internal inspection, run check_vera to get package presence, compaction routing, memory status, subagent/Chimera runtime status, CCC availability/project readiness, 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_status first, then agent/config/compaction.json and any persisted vera.compaction.override session entries.

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