pi-advisor-flow 0.9.2-dev.5 → 0.10.1-dev.1

package/CHANGELOG.md

@@ -8,6 +8,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ### Added
 
+- Native Pi Codemode composition for `ask_advisor`: scripts receive structured advice, IDs, normalized usage, and existing skip metadata, while interactive responses remain unchanged. Documented deterministic-check composition and explicit draft disclosure limits.
+
+## 0.10.0 - 2026-10-02
+
+### Added
+
+- Added an optional `advisorFallbackModel`, selectable from `/advisor-models` and `/advisor-settings`, that retries a failed primary Advisor request once while attributing the response to the model that answered.
+- Added `followUpTo` support for short-lived, session-local Advisor follow-ups that reuse the original post-redaction payload prefix, enforce depth and conversation-advance limits, and render distinct usage status.
 - Added `/advisor-stats`, a local rendered report for retained outcome triggers, adoption, followed-versus-rejected validation pass rates, distinct pseudonymous advice hashes, and the capped ledger time window.
 - Added default-on, toggleable `AGENTS.md` context for trusted Advisor calls, with origin labels, redaction, byte caps, untrusted-rule framing, and explicit withholding for untrusted projects.
 
@@ -20,8 +28,10 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ### Changed
 
+- Fallback retries count as one consultation against the shared Advisor budget; follow-ups count as one consultation each and require a new question without extra attachments or context overrides.
 - Pi 0.87.x and 0.99.x hosts are no longer supported; Pi 1.0.x is now the supported Pi host and the peer range is `^1.0.0`.
 - Updated the development toolchain to the Pi 1.0.0 packages.
+- Updated the Node.js type definitions to 26.6.4.
 
 ## 0.9.1 - 2026-09-30
 

package/README.md

@@ -20,6 +20,8 @@ Keep implementation on a fast model and borrow frontier reasoning only when deci
 - **Configurable review gates** before plans, after repeated failures, and before declaring completion.
 - **Automatic loop detection** for repeated tool calls, with explicit proceed, revise, or blocked decisions.
 - **Separate model and reasoning controls** for the Executor and Advisor, with same-model consultations skipped by default to avoid redundant calls.
+- **Optional Advisor fallback model** that retries provider, auth, and availability failures once without consuming a second consultation budget slot.
+- **Cached Advisor follow-ups** through `followUpTo`, reusing a short-lived, redacted payload prefix for focused questions.
 - **Model whitelist** that can restrict Advisor calls to exact `provider/model` Executor references.
 - **Advisor usage accounting** with per-response token and cost details, normalized usage in Pi's `/cost` totals, and an optional cumulative footer.
 - **Outcome reporting** through `/advisor-stats`, with adoption and validation comparisons over the retained ledger window.
@@ -68,7 +70,7 @@ Reload Pi after installing.
 
 ```text
 /advisor            # Enable the Advisor Flow
-/advisor-models     # Choose the Executor and Advisor models
+/advisor-models     # Choose the Executor, Advisor, and optional fallback models
 /advisor-settings   # Configure behavior, modes, etc.
 /advisor-stats      # Show retained outcome adoption and validation stats
 ```
@@ -87,13 +89,46 @@ In the Settings, enable Simple Mode for a quick start.
 
 Unknown fields in `advisor.json` are preserved for forward compatibility and reported as non-blocking warnings. Invalid recognized values fail their own Advisor call with a clear message instead of blocking every tool call.
 
+## Pi Codemode
+
+With Pi Codemode enabled and the Advisor flow active, call the existing tool through `tools.ask_advisor`; no separate review tool or workflow is needed:
+
+```js
+const commands = ["bun test", "bun run typecheck"];
+const checks = await Promise.all(
+  commands.map(async (command) => {
+    const result = await tools.bash({ command });
+    return {
+      command,
+      exit_code: result.exit_code,
+      truncated: result.truncated,
+    };
+  })
+);
+return await tools.ask_advisor({
+  draft: JSON.stringify({
+    checks,
+    remainingRisk: "Runtime behavior needs review.",
+  }),
+  gitContext: "full",
+});
+```
+
+Gather and filter deterministic results before paying for Advisor reasoning. Nested results are not transcript entries, so they are not automatically available to reconstructed Advisor context. Use the existing `draft` for permitted, concise summaries (8 KiB after optional redaction); these remain untrusted Executor claims, not independently verified evidence. `question` can focus a specific decision; omit it for general reviews. Use `gitContext` for patches so the user's configured disclosure ceiling applies, rather than copying a diff into the draft.
+
+Codemode receives `{ text, adviceId?, advisor?, followUp?, usage?, jev?, skipReason? }`. `text` preserves Advisor Markdown or the existing skip notice; `usage` is the same normalized snapshot shown in response details. Skipped calls have no new `adviceId`. Provider failures and blocked calls reject. Regular consultations never become loop-gate decisions. Interactive responses and usage accounting are unchanged.
+
+Draft text is explicit disclosure: it does **not** inherit the policies of the tools that produced it. Do not copy excluded tool output, secrets, or unconsented file bodies into `draft` or `question`. Jev may also receive the draft when screening is enabled. See [Privacy and data handling](docs/privacy.md).
+
 ## Usage and accounting
 
-Advisor responses show provider-reported input, output, cache, and cost details when available. Successful `ask_advisor` calls also carry normalized usage into Pi's built-in `/cost` totals. Manual consultations and automatic gates keep their own session-local accounting instead, so nothing is double-counted. Missing or partial provider usage is shown as unavailable rather than fabricated as zero. `/advisor-settings` controls both the per-response details and the optional cumulative footer independently.
+Advisor responses show provider-reported input, output, cache, and cost details when available. Successful `ask_advisor` calls also carry normalized usage into Pi's built-in `/cost` totals. Manual consultations and automatic gates keep their own session-local accounting instead, so nothing is double-counted. Missing or partial provider usage is shown as unavailable rather than fabricated as zero. `/advisor-settings` controls both the per-response details and the optional cumulative footer independently. Configure `advisorFallbackModel` or choose **Fallback Advisor model** in the model/settings pickers to retry one failed primary request; the final response is labelled with the model that answered, and both failures are shown together.
+
+A follow-up reuses only the original post-redaction payload in memory. It expires after five minutes, is cleared by a new user turn or three subsequent non-Advisor tool results, and allows at most three chained follow-ups. Use a fresh consultation when it expires or when you need new repository context or attachments.
 
 `/advisor-stats` reads the local outcomes ledger and reports trigger counts, adoption, followed-versus-rejected validation pass rates, distinct pseudonymous advice hashes, and the retained time window. It never fabricates historical cost data; the ledger is capped at 1 MiB and rewritten on overflow.
 
-Successful calls return an opaque `adviceId`. If global outcome logging is enabled, the Executor can call `record_advisor_outcome` once to record whether the advice was adopted and whether final validation passed.
+Successful calls return an opaque `adviceId`. If global outcome logging is enabled, the Executor can call `record_advisor_outcome` once to record whether the advice was adopted and whether final validation passed. A later `ask_advisor` call can pass that ID as `followUpTo` with a new question; the follow-up is counted once against the session budget and shows its responding model and follow-up status.
 
 ## Commands
 
@@ -101,8 +136,8 @@ Successful calls return an opaque `adviceId`. If global outcome logging is enabl
 | --- | --- |
 | `/advisor` | Enable the flow; choose available models when needed. |
 | `/advisor-manual [focus]` | Ask for an immediate second opinion. |
-| `/advisor-models` | Choose the Executor and Advisor models. |
-| `/advisor-settings` | Configure behavior, context, privacy, and limits. |
+| `/advisor-models` | Choose the Executor, Advisor, and optional fallback models. |
+| `/advisor-settings` | Configure behavior, models, context, privacy, and limits. |
 | `/advisor-stats` | Show retained outcome adoption and validation stats. |
 | `/advisor-off` | Disable the flow and persistent activation. |