@jmcombs/pi-qwen-guard 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jeremy Combs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jmcombs/pi-extensions/main/assets/qwen-guard/preview.png" width="250" alt="pi-qwen-guard">
+  <br>
+  <a href="https://www.npmjs.com/package/@jmcombs/pi-qwen-guard"><img src="https://img.shields.io/npm/v/@jmcombs/pi-qwen-guard.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@jmcombs/pi-qwen-guard"><img src="https://img.shields.io/npm/dm/@jmcombs/pi-qwen-guard.svg" alt="npm downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://github.com/jmcombs/pi-extensions/stargazers"><img src="https://img.shields.io/github/stars/jmcombs/pi-extensions?style=social" alt="GitHub stars"></a>
+  <a href="https://github.com/jmcombs/pi-extensions/issues"><img src="https://img.shields.io/github/issues/jmcombs/pi-extensions" alt="Open issues"></a>
+  <a href="https://github.com/sponsors/jmcombs"><img src="https://img.shields.io/badge/Sponsor-30363D?style=flat&logo=GitHub-Sponsors&logoColor=EA4AAA" alt="Sponsor"></a>
+</div>
+
+# @jmcombs/pi-qwen-guard
+
+Automatically detects Qwen 3.6 (or any Qwen model via Ollama) and injects strict incremental-mode rules to prevent "error: terminated" and "Stream ended without finish_reason".
+
+Just install and forget — works on every session.
+
+## Quick Start
+
+```bash
+pi install @jmcombs/pi-qwen-guard
+```
+
+The guard activates silently the moment you start a session with any Qwen model. No commands, no configuration, no secrets.
+
+## How It Works
+
+On `session_start`:
+
+- Inspects `ctx.model.id`.
+- If it contains "qwen", sets an internal flag and shows a one-time success notification:
+  > 🛡️ pi-qwen-guard: Qwen3.6 incremental mode enabled
+
+On every `before_agent_start` (i.e. before each agent turn):
+
+- When the flag is set, appends a block of strict incremental-mode instructions to the system prompt.
+
+The injected rules (abridged):
+
+> CRITICAL QWEN3.6 / OLLAMA INCREMENTAL MODE (enforced every turn):
+>
+> - Never output more than ~70–80 lines of code in any single response.
+> - Prefer the edit tool over write for any file that already exists.
+> - Work in small logical chunks.
+> - After completing a chunk, emit a progress signal that starts with exactly:
+>   `🛡️ pi-qwen-guard: ✅ Chunk complete. File is now X lines.`
+> - You may then continue directly to the next chunk (no need to wait for user approval).
+
+This forces the model to stay within Ollama's streaming limits and eliminates the two fatal errors.
+
+The guard is a no-op for all non-Qwen models.
+
+## Development
+
+This package lives in the [pi-extensions monorepo](https://github.com/jmcombs/pi-extensions).
+
+```bash
+# From the repo root
+npm ci
+npm run check
+```
+
+To try local changes against a real Pi session:
+
+```bash
+pi -e ./packages/qwen-guard
+```
+
+## License
+
+[MIT](./LICENSE) © Jeremy Combs

package/index.ts

@@ -0,0 +1,77 @@
+/**
+ * @jmcombs/pi-qwen-guard
+ *
+ * Automatically detects when a Qwen model (via Ollama) is active inside Pi and
+ * injects strict incremental-mode rules into the system prompt. The rules are
+ * only active while a Qwen model is selected and are removed when you switch
+ * to a different model.
+ *
+ * The guard provides:
+ * - Automatic activation notice when a Qwen model is selected
+ * - Strong behavioral constraints to reduce streaming terminations
+ * - Consistent `🛡️ pi-qwen-guard:` signaling (✅ for progress, ❌ for self-correction)
+ *
+ * Works with or without a separate plan-first / TODO workflow (though results
+ * are generally better when combined with one).
+ *
+ * See:
+ *   - packages/qwen-guard/TESTING.md
+ *   - CONTRIBUTING.md and TEMPLATE.md at the repo root
+ *   - https://pi.dev/docs/extensions
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const QWEN_INSTRUCTIONS = `
+Qwen-safe incremental mode is now active.
+
+Hard rules (these exist to prevent your responses from being killed by Ollama streaming limits):
+
+- Never output more than ~60 lines of code or changes in a single response.
+- After completing any meaningful piece of work (a function, a logical change, a file section, etc.), you must immediately output a single line that starts with exactly "🛡️ pi-qwen-guard: " followed by either ✅ (successful small chunk) or ❌ (you had to stop or self-correct because you were approaching limits).
+- Prefer the edit tool over write for any existing file.
+- Work in small, focused increments. Do not attempt large refactors, multiple files, or broad architectural changes in one response.
+- You may continue to the next small chunk after signaling. You do **not** need explicit user approval after every signal.
+
+For best results with Qwen models on Ollama, strongly consider using a plan-first workflow: create or maintain a TODO.md (or task_plan.md) with small atomic tasks, get the user's explicit approval on the plan before starting major work, and execute one task at a time while keeping the plan updated. This guard will still enforce the size limits and signaling even if you are not using a plan, but combining both is significantly more reliable and prevents streaming failures.
+
+Violating the response size limit or failing to use the required signaling prefix will cause "Stream ended without finish_reason" or similar fatal errors.
+`;
+
+export default function (pi: ExtensionAPI): void {
+  let isQwenModel = false;
+
+  const updateQwenStatus = (modelId: string | undefined) => {
+    isQwenModel = (modelId?.toLowerCase() ?? "").includes("qwen");
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    updateQwenStatus(ctx.model?.id);
+
+    if (isQwenModel) {
+      ctx.ui.notify("🛡️ pi-qwen-guard: Qwen3.6 incremental mode enabled", "info");
+    }
+  });
+
+  pi.on("model_select", (event: unknown) => {
+    // event shape is typically { model: { id: string } }
+    const e = event as { model?: { id?: string }; id?: string };
+    const modelId = e.model?.id ?? e.id;
+    updateQwenStatus(modelId);
+  });
+
+  pi.on("before_agent_start", (event) => {
+    if (!isQwenModel) return;
+
+    const instructions = QWEN_INSTRUCTIONS.trim();
+
+    // Avoid appending multiple times if the prompt is rebuilt
+    if ((event.systemPrompt || "").includes("🛡️ pi-qwen-guard")) {
+      return;
+    }
+
+    return {
+      systemPrompt: (event.systemPrompt || "") + "\n\n" + instructions,
+    };
+  });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@jmcombs/pi-qwen-guard",
+  "version": "0.0.0",
+  "description": "Auto-enables strict incremental mode for Qwen 3.6 (Ollama) to prevent 'terminated' and streaming errors.",
+  "homepage": "https://github.com/jmcombs/pi-extensions/tree/main/packages/qwen-guard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jmcombs/pi-extensions.git",
+    "directory": "packages/qwen-guard"
+  },
+  "bugs": {
+    "url": "https://github.com/jmcombs/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Jeremy Combs",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "qwen",
+    "ollama",
+    "guardrails"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/jmcombs/pi-extensions/main/assets/qwen-guard/preview.png"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}