@mrclrchtr/supi-rtk 1.3.1 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @mrclrchtr/supi-rtk
 
-Transparent RTK-backed bash rewriting for the [pi coding agent](https://github.com/earendil-works/pi).
+Adds RTK-backed bash rewriting to the [pi coding agent](https://github.com/earendil-works/pi).
 
 ## Install
 
@@ -8,48 +8,74 @@ Transparent RTK-backed bash rewriting for the [pi coding agent](https://github.c
 pi install npm:@mrclrchtr/supi-rtk
 ```
 
-> **🧪 Beta package** — not included in the `@mrclrchtr/supi` meta-package.
-> Install directly when you want RTK-backed bash rewriting.
+This is a **beta** package. It is not bundled in `@mrclrchtr/supi`.
 
-## What it adds
+For local development:
 
-This extension wraps the `bash` tool and tries to rewrite commands through the [RTK CLI](https://github.com/joshcho/RTK) before execution.
+```bash
+pi install ./packages/supi-rtk
+```
 
-The goal is lower token usage for repetitive shell commands while preserving the original command when rewriting is unsafe or unavailable.
+After editing the source, run `/reload`.
 
-## Rewrite flow
+## What you get
 
-```text
-bash tool call
-    ↓
-guards.ts checks known lossy collisions
-    ↓
-rewrite.ts runs `rtk rewrite <command>`
-    ↓
-rewritten command or original fallback executes
-    ↓
-tracking.ts records rewrite/fallback stats
-```
+After install, the package intercepts bash execution in two places:
 
-## Safety guards
+- model `bash` tool calls
+- `user_bash` execution paths
 
-Known lossy rewrites are passed through without RTK mediation, including current Biome and ripgrep collision cases.
+For each command, it tries to run `rtk rewrite <command>` first. If RTK returns a usable rewrite, the rewritten command is executed. If not, the original command runs unchanged.
 
-## Requirements
+## Fallback and guard behavior
 
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-- `@mrclrchtr/supi-core`
-- RTK CLI available on `PATH`
+The package falls back to normal bash execution when:
 
-## Development
+- RTK is disabled in settings
+- the `rtk` binary is not available on `PATH`
+- the rewrite times out
+- RTK exits without usable output
+- a guard rule decides the command should bypass rewriting
 
-```bash
-pnpm vitest run packages/supi-rtk/
-pnpm exec tsc --noEmit -p packages/supi-rtk/tsconfig.json
-pnpm exec biome check packages/supi-rtk/
+Current bypass rules include:
+
+- commands prefixed with `RTK_DISABLED=1` or `env RTK_DISABLED=1`
+- commands that invoke `biome`
+- `rg` commands
+- package-manager `lint` commands in projects that use Biome
+
+These guards exist because the current RTK rewrite path can be lossy for those command shapes.
+
+## Settings
+
+This package registers an **RTK** section in `/supi-settings`.
+
+Available settings:
+
+- `enabled` — turn RTK rewriting on or off
+- `rewriteTimeout` — timeout in milliseconds for `rtk rewrite`
+
+Defaults:
+
+```json
+{
+  "rtk": {
+    "enabled": true,
+    "rewriteTimeout": 5000
+  }
+}
 ```
 
-## License
+## Extra integration
+
+- registers an **RTK** provider section for `/supi-context`
+- tracks successful rewrites, fallbacks, and estimated token savings for the current session
+- records debug events through `supi-core`'s debug registry, so `supi-debug` can inspect rewrite and fallback activity when installed
+- warns once per session when RTK is enabled but the `rtk` binary is missing
+
+## Source
 
-MIT
+- `src/rtk.ts` — extension wiring, bash interception, settings, and context-provider registration
+- `src/rewrite.ts` — `rtk rewrite` execution and result classification
+- `src/guards.ts` — bypass rules for known lossy rewrites
+- `src/tracking.ts` — per-session rewrite statistics

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -1,65 +1,78 @@
 # @mrclrchtr/supi-core
 
-Shared infrastructure for SuPi packages.
+Shared infrastructure for SuPi extensions.
+
+This package is mainly for extension authors. It gives you a common config system, settings plumbing, context helpers, registries, and a small extension surface that registers `/supi-settings`.
 
 ## Install
 
-Use it as a dependency in another extension package:
+### As a dependency for another extension
 
 ```bash
 pnpm add @mrclrchtr/supi-core
 ```
 
-## Package role
-
-`@mrclrchtr/supi-core` now has two explicit surfaces:
+### As a pi package
 
-- `@mrclrchtr/supi-core/api` — shared library helpers for other SuPi packages
-- `@mrclrchtr/supi-core/extension` — a minimal pi extension that registers `/supi-settings`
-
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
+```bash
+pi install npm:@mrclrchtr/supi-core
+```
 
-## What it provides
+Installing it as a pi package adds the minimal `/supi-settings` extension surface.
 
-Current exports cover:
+## Package surfaces
 
-- shared config loading, scoped reads, writes, and key removal
-- config-backed settings registration helpers for `/supi-settings`
-- the shared settings registry, overlay UI, and `registerSettingsCommand()` helper
-- XML `<extension-context>` wrapping plus context-message utilities
-- context-provider and debug-event registries reused across SuPi packages
-- project root and path helpers reused by packages such as `supi-lsp`
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/extension` — minimal pi extension that registers `/supi-settings`
 
-## Config system
+## What you get from the API
 
-Config resolution order:
+### Config helpers
 
-```text
-defaults <- global <- project
-```
+- `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
+- `loadSupiConfigForScope()` — load one scope at a time for settings UIs
+- `writeSupiConfig()` — persist values
+- `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
 
 - global: `~/.pi/agent/supi/config.json`
 - project: `.pi/supi/config.json`
 
-Main helpers:
+### Settings helpers
+
+- `registerSettings()` — register an arbitrary settings section
+- `registerConfigSettings()` — register a config-backed settings section with scoped persistence helpers
+- `registerSettingsCommand()` — register `/supi-settings`
+- `openSettingsOverlay()` — open the shared settings UI directly
+- `createInputSubmenu()` — helper for simple text-entry submenus
+
+The built-in settings UI supports:
 
-- `loadSupiConfig()` — effective merged config (`defaults <- global <- project`)
-- `loadSupiConfigForScope()` — raw single-scope config for settings UIs (`defaults <- selected scope`)
-- `writeSupiConfig()`
-- `removeSupiConfigKey()`
-- `registerConfigSettings()`
+- project/global scope toggle
+- grouped extension sections
+- searchable setting lists
 
-## Context and settings helpers
+### Context helpers
 
-- `wrapExtensionContext()`
+- `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
 - `findLastUserMessageIndex()`
 - `getContextToken()`
+- `getPromptContent()`
 - `pruneAndReorderContextMessages()`
-- `registerSettings()`
-- `registerSettingsCommand()`
-- `openSettingsOverlay()`
+- `restorePromptContent()`
+
+### Shared registries
+
+- context-provider registry for `/supi-context`
+- debug-event registry for producers that want shared debug capture
+- settings registry used by `/supi-settings`
+
+### Project and session helpers
+
+- project-root detection and directory walking helpers such as `findProjectRoot()` and `walkProject()`
+- active-branch session helper: `getActiveBranchEntries()`
+- terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
 ## Example
 
@@ -80,17 +93,15 @@ registerConfigSettings({
 });
 
 const message = wrapExtensionContext("my-extension", "hello", {
-  turn: 1,
   file: "CLAUDE.md",
+  turn: 1,
 });
 ```
 
-## Requirements
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-
 ## Source
 
-- Library surface: `src/api.ts`
-- Extension surface: `src/extension.ts`
+- `src/api.ts` — exported library surface
+- `src/extension.ts` — minimal `/supi-settings` entrypoint
+- `src/config.ts` — shared config loading and writing
+- `src/config-settings.ts` — config-backed settings registration helper
+- `src/settings-ui.ts` — shared settings overlay

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{config-settings.ts → config/config-settings.ts}

@@ -2,9 +2,9 @@
 // Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
+import type { SettingsScope } from "../settings/settings-registry.ts";
+import { registerSettings } from "../settings/settings-registry.ts";
 import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
-import type { SettingsScope } from "./settings-registry.ts";
-import { registerSettings } from "./settings-registry.ts";
 
 export interface ConfigSettingsHelpers {
   /** Write a key to the selected scope's config section. */

package/node_modules/@mrclrchtr/supi-core/src/{context-provider-registry.ts → context/context-provider-registry.ts}

@@ -3,7 +3,7 @@
 // Extensions declare context data providers via `registerContextProvider()` during their
 // factory function. The `/supi-context` command reads them via `getRegisteredContextProviders()`.
 
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export interface ContextProvider {
   /** Unique identifier — e.g. "rtk" */

package/node_modules/@mrclrchtr/supi-core/src/extension.ts

@@ -1 +1 @@
-export { registerSettingsCommand as default } from "./settings-command.ts";
+export { registerSettingsCommand as default } from "./settings/settings-command.ts";

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{settings-registry.ts → settings/settings-registry.ts}

@@ -4,7 +4,7 @@
 // factory function. The generic settings UI reads them via `getRegisteredSettings()`.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export type SettingsScope = "project" | "global";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-rtk",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "SuPi RTK extension — transparent bash command rewriting via RTK for token savings",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.3.1"
+    "@mrclrchtr/supi-core": "1.4.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/rtk.ts

@@ -13,6 +13,7 @@ import {
 } from "@mrclrchtr/supi-core/api";
 import { shouldBypassRtkRewrite } from "./guards.ts";
 import { type RtkRewriteFailureReason, rtkRewriteDetailed } from "./rewrite.ts";
+import { promptGuidelines } from "./tool/guidance.ts";
 import { getStats, recordFallback, recordRewrite, resetTracking } from "./tracking.ts";
 
 const RTK_SECTION = "rtk";
@@ -244,13 +245,7 @@ export default function rtkExtension(pi: ExtensionAPI) {
 
   pi.registerTool({
     ...baseBashTool,
-    // TODO(rtk-ai/rtk#1813): Remove these promptGuidelines once the upstream issue
-    // "vitest run output truncates failures" is fixed in a released RTK version.
-    // After that, default compact output will list all failing tests and this
-    // guidance will no longer be necessary.
-    promptGuidelines: [
-      "When running test commands (vitest, jest, pytest, cargo test, etc.), RTK may intercept and compact the output. To see all test failures without truncation, pass `-v` to the command (e.g. `pnpm vitest -v run`). To bypass RTK entirely and get raw output, prefix with `RTK_DISABLED=1`.",
-    ],
+    promptGuidelines,
     // biome-ignore lint/complexity/useMaxParams: pi tool execute signature
     async execute(toolCallId, params, signal, onUpdate, ctx) {
       const bashTool = createRtkAwareBashTool(ctx.cwd, ctx);

package/src/tool/guidance.ts

@@ -0,0 +1,10 @@
+// Prompt guidance for the RTK bash override.
+//
+// TODO(rtk-ai/rtk#1813): Remove this promptGuidelines entry once the upstream
+// issue "vitest run output truncates failures" is fixed in a released RTK
+// version. After that, default compact output should list all failing tests and
+// this guidance will no longer be necessary.
+
+export const promptGuidelines = [
+  "Use bash with `-v` when running test commands (vitest, jest, pytest, cargo test, etc.) because the RTK bash override may compact failure output. Prefix a bash command with `RTK_DISABLED=1` to bypass the RTK bash override entirely and get raw output.",
+];