Skip to content

architecture.md

Latest commit

 

History

History
118 lines (86 loc) · 3.6 KB

architecture.md

File metadata and controls

118 lines (86 loc) · 3.6 KB

Architecture (Current)

Overview

pi-prompt-suggester has five runtime pieces:

  1. Suggestion pipeline (runs on agent_end)
  2. Agentic reseed runner (background, non-blocking)
  3. Steering tracker (session/branch-aware)
  4. UI sink (ghost suggestion + usage line)
  5. Persistent observability log (.pi/suggester/logs/events.ndjson)

1) State model

Project-global (file)

./.pi/suggester/seed.json

Contains:

  • seed summaries (intent/objectives/constraints/principles/status)
  • key files (+ hashes + category)
  • required-category findings (vision, architecture, principles_guidelines) with found/not_found rationale
  • generator/prompt/config fingerprints

Session/branch-local (extension-owned files)

.pi/suggester/sessions/<session-id>/...

Contains:

  • last shown suggestion
  • steering history (accepted_exact | accepted_edited | changed_course)
  • session-persistent suggester usage/cost counters
  • session-persistent seeder usage/cost counters
  • combined totals for status/UI display

Older suggester-state / suggester-usage Pi custom entries are only used as a one-time legacy migration source.

2) Agentic seeding

Reseeding is queued async and never blocks interaction.

Trigger points:

  • session lifecycle events (session_start/tree/fork/switch)
  • agent_end stale check
  • manual /suggester reseed

Seeder implementation:

  • iterative model loop with read-only tools: ls, find, grep, read
  • explicit required-category coverage in final output
  • accepts found: false when rationale is provided
  • multiple files per category supported

Validation requires:

  • all required categoryFindings
  • non-empty rationale for each
  • if found=true, at least one matching key file tagged with that category

3) Suggestion pipeline

Trigger:

  • agent_end only

Inputs:

  • assistant completion + status (success | error | aborted)
  • recent user prompts
  • tool signals + touched files + unresolved questions
  • full intent seed summaries + categorized key files + category findings
  • recent accepted/changed steering examples

Behavior:

  • non-success turns (error, aborted) can fast-path to continue (configurable)
  • output is one suggestion or [no suggestion]
  • multi-line suggestions allowed; bounded by maxSuggestionChars

4) UI behavior

  • Suggestions can ghost in the editor when safe (idle, no pending messages, editor-empty policy; multiline requires an empty editor)
  • Space-to-accept when the editor is empty
  • Non-compatible cases hide the ghost suggestion; the suggestion text is never moved into the below-editor widget
  • The stock pi footer is preserved
  • Compact suggester info uses status lines
  • Richer suggester state/warnings use a below-editor widget

5) Observability

Persistent log file:

  • .pi/suggester/logs/events.ndjson

Logged events include:

  • seeder run start/completion/exhaustion
  • seeder tool requests/results and validation failures
  • suggestion turn received, suggestion generated, no-suggestion
  • steering classification events

Inspection:

  • /suggester seed-trace [limit]
  • /suggester status includes log path plus usage breakdown (suggester/seeder/combined)

6) Commands

  • /suggester status
  • /suggester reseed
  • /suggester model [show|set|clear] ... (writes project override .pi/suggester/config.json)
  • /suggester thinking [show|set|clear] ... (writes project override .pi/suggester/config.json)
  • /suggester config [show|set [project|user] <path> <value>|reset [project|user|all]]
  • /suggesterSettings (interactive TUI settings menu)
  • /suggester instruction [show|set|clear]
  • /suggester seed-trace [limit]