paseo-prompt-kit 0.5.2 → 0.5.5

package/README.md

@@ -1,8 +1,8 @@
 # PromptKit
 
-PromptKit is a Paseo plugin (id `prompt-kit`) that rewrites the prompt in your Composer. It adds one `PromptKit` pill to the Composer's track bar and a `/rewrite <prompt>` slash command; the default action is `General`. Running it rewrites the current Composer text in place, in your own voice (first person, speaking to the agent), keeps your language and every protected literal (URLs, absolute paths, shell commands, code blocks, model names, tool names), restores focus, and never sends the prompt. You review the result and send it yourself.
+PromptKit is a Paseo plugin that rewrites the prompt in your Composer before you send it. It adds a `PromptKit` pill to the Composer and a `/rewrite <prompt>` slash command. The rewrite replaces the Composer text in your own voice — first person, speaking to the agent — and keeps your language and every protected literal (URLs, absolute paths, shell commands, code blocks, model and tool names).
 
-Rewriting has three paths, chosen in Settings. The default runs the selected model through the provider's own CLI, headlessly, in a temporary directory — no Paseo agent, no tab, no archive. Your primary conversation never receives a rewrite turn and never changes provider or session. The third path posts straight to an API you configure (OpenAI, Anthropic, Google Gemini, Cloudflare Workers AI, or anything speaking one of those protocols) when a CLI cold start is too slow or no CLI exists.
+The rewrite runs one of three ways, chosen in Settings: the agent's own provider CLI with the model the Composer shows (the default), a provider CLI with a model you pick, or a direct request to an API you configure (OpenAI, Anthropic, Google Gemini, Cloudflare Workers AI, or anything speaking one of those protocols). A CLI runs headlessly in a temporary directory — no Paseo agent, no tab, no archive — so your conversation never receives a rewrite turn.
 
 See [CHANGELOG.md](CHANGELOG.md) for release notes.
 
@@ -10,15 +10,35 @@ See [CHANGELOG.md](CHANGELOG.md) for release notes.
 
 - **The pill** — write your prompt, press `PromptKit`. The text is rewritten in place; a leading `/rewrite ` left in the text is ignored. Available once the agent exists, so on a new seat it appears after the first message.
 - **`/rewrite <prompt>`** — type the command with the prompt after it and press Enter. Paseo empties the Composer and hands the text to PromptKit, which puts the `/rewrite …` line straight back, dims it with a light sweep while it works, and then replaces it with the rewrite. A failed rewrite leaves your line in place. Available immediately, including on a new seat before its first message. Because no agent exists yet on a draft, `/rewrite` cannot use `Current agent model`; choose `Dedicated model` or `Direct API` with a selected endpoint and model in Settings, or use the pill once the agent exists.
-- **The PromptKit sheet** (mobile) — write in the Composer as usual and press the pill. A sheet slides up already holding your text and rewrites it at once. Press **Rewrite** again until it reads right, then **Send**: the message goes to the agent, the Composer is cleared, the sheet closes. **✕** closes the sheet and leaves the Composer untouched.
+- **The PromptKit sheet** (mobile) — write in the Composer as usual and press the pill. A sheet slides up holding your text. With one enabled action it rewrites at once and **Rewrite** runs it again; with several, each action has its own button and nothing runs until you press one. **Send** gives the message to the agent, clears the Composer and closes the sheet. **✕** closes the sheet and leaves the Composer untouched.
 
 No path sends the message on its own. You review the result and send it yourself.
 
+## The General action
+
+`General` is the one action that ships. It turns the draft into a clear instruction the agent can act on: the concrete action, each constraint made checkable, the working steps for that kind of task (find the cause first, follow the codebase's existing way, keep the change scoped), and how the agent knows it is done. It never invents files, numbers, requirements or decisions the draft does not contain, and it never writes about you as "the user". Add your own actions under Settings → **Custom actions**.
+
 ## Requirements
 
-- Paseo Desktop or Web, version `>=0.9.0` (`paseo-plugin.json`). The plugin is built and tested against the 0.9.0 SDK.
-- For the CLI transports: a provider/model reachable by the daemon, and that provider's CLI on the daemon's `PATH`.
-- For the API transport: an endpoint URL, a model id, and a key — see [API keys](#api-keys).
+- Paseo `>=0.9.0` (Desktop, Web or mobile). Built and tested against the 0.9.0 plugin SDK.
+- For **Provider CLI**: that provider's CLI on the daemon's `PATH`, and a model it can reach.
+- For **Direct API**: an endpoint URL, a model id, and a key — see [API keys](#api-keys).
+
+## Install from npm (recommended)
+
+PromptKit is published on npm as [`paseo-prompt-kit`](https://www.npmjs.com/package/paseo-prompt-kit). On Paseo 0.9:
+
+```bash
+paseo plugin add npm:paseo-prompt-kit
+paseo plugin ls
+```
+
+Pin a release by adding its version, for example `npm:paseo-prompt-kit@0.5.5`. The plugin id stays `prompt-kit`, so reload and logs use that id:
+
+```bash
+paseo plugin reload prompt-kit
+paseo plugin logs prompt-kit
+```
 
 ## Install from a local directory
 
@@ -39,7 +59,7 @@ paseo plugin logs prompt-kit
 
 ## Install from Git
 
-After the repository is published, install the managed Git checkout:
+Install a managed Git checkout:
 
 ```bash
 paseo plugin install hungcuong9125/paseo-prompt-kit --ref main
@@ -49,24 +69,24 @@ paseo plugin ls
 `--ref` chooses the initial branch, tag, or commit once; later `paseo plugin update prompt-kit` follows the remote's default HEAD. Pin a release instead of tracking `main` by giving `--ref` a tag:
 
 ```bash
-paseo plugin install hungcuong9125/paseo-prompt-kit --ref v0.5.2
+paseo plugin install hungcuong9125/paseo-prompt-kit --ref v0.5.5
 ```
 
 `paseo plugin ls` reports the installed commit.
 
 ## Settings
 
-Open it from Paseo Settings → Plugins → the `…` menu on `prompt-kit` → **Settings**. The bar at the top says whether a rewrite would run and over which path, names the reason when it would not, and holds **Save** / **Discard** once something has changed. Nothing is written until Save.
+Open PromptKit's settings from Paseo Settings → Plugins → the `…` menu on `prompt-kit` → **Settings**. The bar at the top says whether a rewrite would run and over which path, names the reason when it would not, and holds **Save** / **Discard** once something has changed. Nothing is written until Save.
 
 ![PromptKit settings with the default path: Provider CLI, current agent model, output in the prompt's language](docs/images/settings-provider-cli.png)
 
 The screen reads top to bottom in setup order:
 
-1. **Actions** — one switch per action, bundled or custom; up to 6 can be on. One enabled action makes the pill rewrite at once; two or more make it a menu (on mobile, one button per action in the sheet); none hides the pill. A lone action shows no switch. Saving updates every pill at once.
-   **Custom actions** — your own actions, written as action-pack JSON in a text box on the same screen: **Add** opens a sample (Blank template, Copy of General, Execution brief, Plan first, Review request, Make concise, or a copy of one of yours), you change the id, title and instructions, **Apply** checks the JSON, and **Save** stores it. They run through the same rewrite as the bundled ones.
-2. **Rewrite engine** — Transport, Model source (Provider CLI only) and Output language. Every other section appears only when these need it.
-3. **Dedicated model** (CLI + Dedicated) or **API endpoint** (Direct API).
-4. **Advanced** (collapsed) — timeout and the two per-provider overrides.
+1. **Actions** — one switch per action, bundled or custom; up to 6 can be on. One enabled action makes the pill rewrite at once; two or more make it a menu (on mobile, one button per action in the sheet); none hides the pill. A lone action shows as **Always on**, with no switch. Saving updates every pill at once.
+2. **Custom actions** — your own actions, written as action-pack JSON in a text box on the same screen. **Add** opens a sample (Blank template, Copy of General, Execution brief, Plan first, Review request, Make concise, or a copy of one of yours); change the id, title and instructions, press **Apply** to check the JSON, then **Save**. They run through the same rewrite as `General`.
+3. **Rewrite engine** — Transport, Model source (Provider CLI only) and Output language. Every other section appears only when these need it.
+4. **Dedicated model** (Provider CLI with Dedicated model) or **API endpoint** (Direct API).
+5. **Advanced** (collapsed) — timeout and the two per-provider overrides.
 
 ### Transport
 
@@ -94,14 +114,14 @@ On `Direct API`, an agent whose provider is mapped under **Advanced → Endpoint
 
 ### API endpoint
 
-Choose an endpoint — presets and your saved custom endpoints are listed A–Z (Anthropic, Cloudflare Workers AI, Google Gemini, Local server, OpenAI, OpenRouter), with **Custom endpoint…** last — fill in the base URL, pick a **Key source** (see [API keys](#api-keys)), and press **Test**. A successful test fills the **Model** list from the endpoint; the rewrite refuses a model outside that list. When a list has more than 8 models, a **Filter models** row above Model narrows the dropdown by name or id; the saved model always stays in it. Save is blocked while the endpoint cannot work (for example an empty base URL), with the reason in the status bar.
+Choose an endpoint — presets and your saved custom endpoints are listed A–Z (Anthropic, Cloudflare Workers AI, Google Gemini, Groq, Local server, OpenAI, OpenRouter), with **Custom endpoint…** last — fill in the base URL, pick a **Key source** (see [API keys](#api-keys)), and press **Test**. A successful test fills the **Model** list from the endpoint; the rewrite refuses a model outside that list. When a list has more than 8 models, a **Filter models** row above Model narrows the dropdown by name or id; the saved model always stays in it. Save is blocked while the endpoint cannot work (for example an empty base URL), with the reason in the status bar.
 
 ![PromptKit settings on Direct API with the Google Gemini endpoint: key source, connection test, model filter and model](docs/images/settings-direct-api.png)
 
 ### Advanced
 
 - `Timeout (ms)`: how long a rewrite may run, default `90000`, allowed range `1000`–`600000`. The daemon caps one plugin call at 30 s, so the screen notes when a budget above that cannot be reached.
-- `CLI per provider` (Provider CLI): lists only the providers you have overridden, plus an Add row. A profile named after its CLI (`pi-peer`, `codex-lead`) resolves on its own and needs no entry; an unresolved provider is refused, never guessed.
+- `CLI per provider` (Provider CLI): lists only the providers you have overridden, plus an Add row. A provider named after its CLI (for example `pi` or `codex`) resolves on its own and needs no entry; an unresolved provider is refused, never guessed.
 - `Endpoint per provider` (Direct API): lists only mapped providers, plus an Add row. Pressing the pill in an agent of a mapped provider sends that agent's own model to the endpoint over HTTP. A mapped provider ignores the Model chosen under API endpoint.
 
 Settings are host-scoped and persist across plugin reload.
@@ -161,7 +181,7 @@ Prefer, in this order:
 2. **Editing `secrets.json` yourself** on the daemon's machine, as above — the key never passes through the Paseo app.
 3. **The API key field** — only when neither of the above is practical.
 
-With Key source `secrets.json`, the API endpoint section shows an **API key** field (masked) and a **Store key** row. **Save** writes the value under the endpoint's Key variable in `secrets.json`: other entries and fields are kept, the directory is created `0700` and the file written `0600` through a temporary file and a rename, and a malformed file is refused rather than overwritten. The field is cleared after saving. The key is write-only: the screen only says whether a value is stored, and **Remove stored key** deletes that one entry. The value never enters the settings document, a log, or an RPC answer. Two clients saving at the same moment can overwrite each other's change.
+With Key source `secrets.json`, the API endpoint section shows an **API key** field (masked) and a **Store API key** row. **Save** writes the value under the endpoint's Key variable in `secrets.json`: other entries and fields are kept, the directory is created `0700` and the file written `0600` through a temporary file and a rename, and a malformed file is refused rather than overwritten. The field is cleared after saving. The key is write-only: the screen only says whether a value is stored, and **Remove stored API key** deletes that one entry. The value never enters the settings document, a log, or an RPC answer. Two clients saving at the same moment can overwrite each other's change.
 
 ### What PromptKit guarantees about keys
 
@@ -223,6 +243,7 @@ An endpoint that lists `models` restricts the choice to that list, and a model o
 |---|---|
 | `missing_api_key` | The endpoint's Key source has no value for its key variable, `secrets.json` is missing or malformed, or the secrets directory is not absolute |
 | `api_endpoint_unknown` | The selected or mapped endpoint id is not defined in `apiEndpoints` |
+| `invalid_model` | The model is not in the endpoint's `models` list |
 | `api_http_error` | The endpoint answered a non-2xx status, or was unreachable |
 | `api_bad_response` | The answer was not JSON, or carried no text |
 | `timeout` | The request exceeded `Timeout (ms)` |
@@ -233,9 +254,8 @@ Every one of these leaves the Composer text untouched.
 
 - In-place rewriting works on Desktop and Web only: the mobile app renders the Composer as a native text input with no DOM, and Paseo 0.9.0 exposes no plugin API for Composer text. On mobile the `PromptKit` pill opens the **PromptKit sheet** instead (see above); it reads and clears the Composer through the app's React tree rather than the DOM, which a Paseo update can break in the same way. Nothing is copied or sent on its own. `/rewrite` is not available on mobile. On Web, a refusal names what was found (no Composer, none visible, or more than one visible).
 - Requires Paseo `>=0.9.0`. Because text access depends on the Composer DOM (or, on mobile, the React tree), a Paseo UI change can break it even when the public plugin SDK is compatible.
-- No auto-send. PromptKit only replaces the Composer text; you send the message.
 - PromptKit refuses to replace text you edited while a rewrite was running, and refuses when more than one Composer (or none) is visible.
-- One bundled action: `General` turns the draft into a clear instruction the agent can act on — the concrete action, each constraint made checkable, the working steps for that kind of task (find the cause first, follow the codebase's existing way, keep the change scoped), and when it is done. It never invents files, numbers, requirements or decisions the draft does not contain, and it writes as you, speaking to the agent — never about "the user". Add your own under Settings → Custom actions, or bundle one as a JSON file — see `docs/EXTENDING.md`.
+- Only `General` ships. Any other action is a custom action you write in Settings, or a pack you bundle as a JSON file — see `docs/EXTENDING.md`.
 - The API transport does not stream: it makes one request and waits for the whole answer. A slow endpoint can exceed the daemon's 30-second plugin-call cap, in which case the host reports a timeout before PromptKit's own `Timeout (ms)` can fire.
 - No OAuth or token refresh: an endpoint uses a static key. A provider that needs an interactive login is better served by the CLI transport.
 

package/client/settings/api-endpoints.ts

@@ -52,6 +52,16 @@ export const ENDPOINT_PRESETS: readonly EndpointPreset[] = [
     accountIdVar: "",
     note: "AI Studio",
   },
+  {
+    id: "groq",
+    label: "Groq",
+    protocol: "openai",
+    baseUrl: "https://api.groq.com/openai/v1",
+    keySource: "env",
+    apiKeyEnv: "GROQ_API_KEY",
+    accountIdVar: "",
+    note: "OpenAI-compatible, very fast",
+  },
   {
     id: "openrouter",
     label: "OpenRouter",

package/client/sheet/rewrite-sheet.tsx

@@ -32,6 +32,8 @@ const drafts = new Map<string, string>();
 
 /** Action buttons per row when several actions are enabled. */
 const ACTIONS_PER_ROW = 2;
+/** One grid cell: every cell, filled or empty, takes an equal share of the row. */
+const GRID_CELL = { flexGrow: 1, flexShrink: 1, flexBasis: 0 } as const;
 
 function rows<T>(items: readonly T[]): T[][] {
   const out: T[][] = [];
@@ -206,17 +208,17 @@ export function createRewriteSheet(locate: ComposerLocator): ComponentType<Plugi
           ? rows(choices).map((row) => (
               <View key={row.map((action) => action.id).join(",")} style={{ flexDirection: "row", gap: SPACE.md }}>
                 {row.map((action) => (
-                  <Button
-                    key={action.id}
-                    theme={theme}
-                    label={action.title}
-                    fill
-                    onPress={() => void runRewrite(value, action.id)}
-                    disabled={busy !== "idle" || value.trim() === ""}
-                    testID={`prompt-kit-sheet-action-${action.id}`}
-                  />
+                  <View key={action.id} style={GRID_CELL}>
+                    <Button
+                      theme={theme}
+                      label={action.title}
+                      onPress={() => void runRewrite(value, action.id)}
+                      disabled={busy !== "idle" || value.trim() === ""}
+                      testID={`prompt-kit-sheet-action-${action.id}`}
+                    />
+                  </View>
                 ))}
-                {row.length < ACTIONS_PER_ROW ? <View style={{ flex: 1 }} /> : null}
+                {row.length < ACTIONS_PER_ROW ? <View style={GRID_CELL} /> : null}
               </View>
             ))
           : null}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-prompt-kit",
-  "version": "0.5.2",
+  "version": "0.5.5",
   "license": "MIT",
   "description": "PromptKit - rewrite and transform prompts directly from the Paseo composer.",
   "keywords": [

package/server/transports/cli/family.ts

@@ -15,7 +15,7 @@ export interface CliInvocation {
 }
 
 export interface CliRequest {
-  /** The model id as the agent snapshot reports it, e.g. `workbuddy/deepseek-v4.1-flash`. */
+  /** The model id as the agent snapshot reports it, e.g. `openai/gpt-4.1-mini`. */
   readonly model: string;
   readonly thinkingOptionId: string | null;
   /** Instruction text. Replaces the CLI's own default system prompt where supported. */
@@ -34,6 +34,8 @@ export interface CliFamily {
   buildInvocation(request: CliRequest): CliInvocation;
   /** Extracts the final answer from captured stdout, or null when there is none. */
   parseOutput(stdout: string): string | null;
+  /** The failure the CLI itself reports in stdout, or null when it reports none. */
+  parseError(stdout: string): string | null;
 }
 
 /** Collects the text parts of a pi/opencode-style JSONL event stream. */
@@ -104,8 +106,21 @@ export const piFamily: CliFamily = {
     lastJsonlText(stdout, (event) =>
       event.type === "turn_end" ? piMessageText(event.message) : null,
     ),
+  parseError: () => null,
 };
 
+/** The single JSON result object `claude -p --output-format json` prints, or null. */
+function claudeResult(stdout: string): { result?: unknown; is_error?: unknown } | null {
+  const start = stdout.indexOf("{");
+  if (start === -1) return null;
+  try {
+    const parsed: unknown = JSON.parse(stdout.slice(start));
+    return parsed !== null && typeof parsed === "object" ? (parsed as { result?: unknown; is_error?: unknown }) : null;
+  } catch {
+    return null;
+  }
+}
+
 export const claudeFamily: CliFamily = {
   id: "claude",
   promptDelivery: "stdin",
@@ -128,17 +143,16 @@ export const claudeFamily: CliFamily = {
     return { command: "claude", args };
   },
   parseOutput: (stdout) => {
-    const start = stdout.indexOf("{");
-    if (start === -1) return null;
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(stdout.slice(start));
-    } catch {
-      return null;
-    }
-    if (parsed === null || typeof parsed !== "object") return null;
-    const result = (parsed as { result?: unknown }).result;
-    return typeof result === "string" ? result : null;
+    const parsed = claudeResult(stdout);
+    if (parsed === null || parsed.is_error === true) return null;
+    return typeof parsed.result === "string" ? parsed.result : null;
+  },
+  // An auth or API failure still prints a result object, flagged `is_error`, whose
+  // `result` is the error text rather than an answer.
+  parseError: (stdout) => {
+    const parsed = claudeResult(stdout);
+    if (parsed === null || parsed.is_error !== true) return null;
+    return typeof parsed.result === "string" && parsed.result.trim() !== "" ? parsed.result : "Claude reported an error.";
   },
 };
 
@@ -171,6 +185,7 @@ export const codexFamily: CliFamily = {
       const typed = item as { type?: unknown; text?: unknown };
       return typed.type === "agent_message" && typeof typed.text === "string" ? typed.text : null;
     }),
+  parseError: () => null,
 };
 
 export const opencodeFamily: CliFamily = {
@@ -190,6 +205,7 @@ export const opencodeFamily: CliFamily = {
       const text = (part as { text?: unknown }).text;
       return typeof text === "string" ? text : null;
     }),
+  parseError: () => null,
 };
 
 const FAMILIES: readonly CliFamily[] = [piFamily, claudeFamily, codexFamily, opencodeFamily];

package/server/transports/cli/runner.ts

@@ -22,7 +22,17 @@ export interface CliRewriteDependencies {
 
 export type CliRewriteResult =
   | { readonly ok: true; readonly text: string }
-  | { readonly ok: false; readonly code: "timeout" | "spawn_failed" | "empty_output"; readonly message: string };
+  | {
+      readonly ok: false;
+      readonly code: "timeout" | "spawn_failed" | "empty_output" | "generation_failed";
+      readonly message: string;
+    };
+
+/** Enough of a CLI's own error text to recognise it, on one line. */
+function firstLine(text: string, max = 200): string {
+  const line = text.split("\n").map((part) => part.trim()).find((part) => part !== "") ?? "";
+  return line.length <= max ? line : `${line.slice(0, max - 1)}…`;
+}
 
 /**
  * Runs one rewrite through a CLI in a scratch directory.
@@ -74,6 +84,27 @@ export async function runCliRewrite(
       return { ok: false, code: "timeout", message: "The rewrite timed out." };
     }
 
+    // A failed run never becomes a rewrite: its stdout can hold an error text
+    // that would otherwise read like an answer.
+    const reported = input.family.parseError(result.stdout);
+    if (reported !== null) {
+      return {
+        ok: false,
+        code: "generation_failed",
+        message: `The rewrite CLI "${input.family.id}" reported an error: ${firstLine(reported)}`,
+      };
+    }
+    if (result.exitCode !== 0) {
+      const detail = firstLine(result.stderr);
+      return {
+        ok: false,
+        code: "generation_failed",
+        message: `The rewrite CLI "${input.family.id}" exited with ${
+          result.exitCode === null ? "a signal" : `code ${result.exitCode}`
+        }${detail === "" ? "." : `: ${detail}`}`,
+      };
+    }
+
     const text = input.family.parseOutput(result.stdout);
     if (text === null || text.trim() === "") {
       return {

package/shared/settings.ts

@@ -38,11 +38,10 @@ export const promptKitSettingsSchema = z.object({
   dedicatedModel: z.string().min(1).nullable().default(null),
   dedicatedThinkingOptionId: z.string().min(1).nullable().default(null),
   /**
-   * Maps a Paseo provider id to the CLI family that runs it. Paseo names a
-   * built-in provider after its CLI (`pi`, `codex`) and a custom profile after
-   * the role it plays (`pi-peer`, `codex-lead`), so the leading segment resolves
-   * most ids without an entry here. An entry is needed only for a profile whose
-   * id does not mention its CLI, and an unknown id fails closed either way.
+   * Maps a Paseo provider id to the CLI family that runs it. A provider named
+   * after its CLI (`pi`, `codex`), or whose id starts with that name, resolves
+   * without an entry here. An entry is needed only for a provider whose id does
+   * not mention its CLI, and an unknown id fails closed either way.
    */
   providerCli: z.record(z.string(), z.enum(CLI_FAMILY_IDS)).default({}),
   /** The API endpoints this host can reach. Key values are never stored here. */