@openlines/opl-pi-sht 0.2.1 → 0.2.3

package/README.md

@@ -14,6 +14,14 @@
 
 A portable collection of various Pi coding agent extensions. Repository directories and config files use `opl-`; established Pi-facing commands and tool names stay compatible.
 
+<div align="center">
+
+>
+> ## v0.2.3 (22 Sept 2026) - updated `opl-modes` extension compatibility with latest pi release [now requires pi >= 0.87.0]<br/>see [CHANGELOG.md](CHANGELOG.md) for more details.
+>
+
+</div>
+
 ## Installation
 
 ### Pi package
@@ -76,6 +84,7 @@ Copy mode overwrites matching destinations. Link mode skips existing destination
 | [`opl-webaccess`](extensions/opl-webaccess/README.md)         | Search plus readable URL/PDF retrieval with session recovery.                                                                                                                                                                | `web_search`, `fetch_content`, `get_search_content`; `opl-webaccess.json`.                                     |
 | [`opl-browser`](extensions/opl-browser/README.md)             | Chromium automation via Playwright with structured extraction of rendered pages; single dispatcher tool replacing the chrome-devtools MCP.                                                                                   | `browser` (action-based); `opl-browser.json`.                                                                  |
 | [`opl-ctxtrim`](extensions/opl-ctxtrim/README.md)             | Trims verbose`ctx_*` tool-schema descriptions on outbound provider requests (~67% smaller schema, ~4,700-6,300 tokens/request). Built specifically for the [context-mode](https://github.com/mksglu/context-mode) extension. | No commands/tools; no config.                                                                                  |
+| [`opl-guardian`](extensions/opl-guardian/README.md)           | Drops malformed assistant tool calls before session persistence or replay, with project-local JSONL evidence. | No commands/tools; no config.                                                                                  |
 | [`opl-todo`](extensions/opl-todo/README.md)                   | Branch-aware task tool, overlay, and task list.                                                                                                                                                                              | `todo`, `/todos`; `opl-todo.json`.                                                                             |
 | [`opl-questionnaire`](extensions/opl-questionnaire/README.md) | Interactive structured-choice tool.                                                                                                                                                                                          | `questionnaire`; no config.                                                                                    |
 | [`opl-input`](extensions/opl-input/README.md)                 | Configurable replacement editor - enhanced [pikit chat-input](https://github.com/adrianapan/pikit) (because pet is life, and configurable). ![pet](images/ss-input-pet.png)                                                                                   | No commands/tools;`opl-input.json`.                                                                            |
@@ -104,9 +113,10 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 
 ### Run the agent without babysitting it
 
-- **`opl-modes`** chat and plan modes swap the active toolset for read-only lists and gate Bash to safe inspection patterns **per shell segment**, so `cat f && node -e '...'`, `cat x & rm -rf /tmp/x`, and `echo "$(node -e ...)"` can no longer ride the first command's allowance. Destructive checks still fire inside otherwise-safe commands (anchored to command position, so `du -sh` and `find . -name '*.sh'` stay allowed; `find -delete`, `find -fprint`, `git log --output`, `sort -o`, `npm audit fix`, `git clean`, `sudo`, and quote-obfuscated `r"m"`/`-del"ete"` are blocked; `env`/`printenv` are not safe-listed). The plan to execute lifecycle keeps exploration and mutation cleanly separated. Add custom modes (like below) for your workflow needs.
+- **`opl-modes`** chat and plan modes swap the active toolset for read-only lists and gate Bash to safe inspection patterns **per shell segment**, so `cat f && node -e '...'`, `cat x & rm -rf /tmp/x`, and `echo "$(node -e ...)"` can no longer ride the first command's allowance. Destructive checks still fire inside otherwise-safe commands (anchored to command position, so `du -sh` and `find . -name '*.sh'` stay allowed; `find -delete`, `find -fprint`, `git log --output`, `sort -o`, `npm audit fix`, `git clean`, `sudo`, and quote-obfuscated `r"m"`/`-del"ete"` are blocked; `env`/`printenv` are not safe-listed). The plan to execute lifecycle keeps exploration and mutation cleanly separated. Add custom modes (like below) for your workflow needs. Execute-mode auto-exit needs pi >= 0.87.0 (the `agent_before_settle` boundary).
 ![custom mode sample](images/ss-mode-custom.png)
 - `load_tools` activation is bounded by the current mode, so a read-only mode cannot be tricked into enabling a write-capable tool.
+- **`opl-guardian`** stops a malformed provider tool-call record from poisoning the session: it removes calls missing an ID or name before Pi persists or replays them, while preserving dropped records in `err/guardian.jsonl` for an upstream report.
 
 
 ### Move through work faster
@@ -137,7 +147,7 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 | If you want to...                  | Install                                                         |
 | ---------------------------------- | --------------------------------------------------------------- |
 | Cut token cost with minimal change | `opl-ctxtrim`, `opl-modes`                                      |
-| Run the agent safely on real repos | `opl-modes` (pulls in the `opl-input` + `opl-footer` UI bundle) |
+| Run the agent safely on real repos | `opl-modes` (pulls in the `opl-input` + `opl-footer` UI bundle), `opl-guardian` |
 | Research and drive the web         | `opl-webaccess`, `opl-browser`                                  |
 | Choose models with data            | `opl-simplebench`                                               |
 | The full, coordinated experience   | all ten                                                         |
@@ -161,6 +171,7 @@ Installing extensions adds tool schemas (name + description + JSON parameters) t
 | `opl-init` | command only (no tool) | ~0 |
 | `opl-input` | UI only | ~0 |
 | `opl-footer` | UI only | ~0 |
+| `opl-guardian` | none (session-integrity guard) | ~0 |
 | `opl-ctxtrim` | none (payload transformer) | net negative |
 
 Command descriptions add roughly another ~120 tokens collectively, and only if your build surfaces them in the prompt or help block.
@@ -218,4 +229,4 @@ A Pi package (npm or Git) still needs the one-time `npx playwright install chrom
 npm test
 ```
 
-Run one extension suite with `npm run test:opl-<name>` for `browser`, `footer`, `init`, `input`, `modes`, `questionnaire`, `todo`, `webaccess`, `simplebench`, or `ctxtrim`. Every helper, functional, and selected-entrypoint smoke check uses Bun's named-test reporter; output includes per-test status, timings, and pass/fail totals. Functional tests cover deterministic helpers where practical; smoke tests bundle entrypoints and parse config. They do not test live TUI behavior, provider credentials, network access, or PDF extraction.
+Run one extension suite with `npm run test:opl-<name>` for `browser`, `footer`, `guardian`, `init`, `input`, `modes`, `questionnaire`, `todo`, `webaccess`, `simplebench`, or `ctxtrim`. Every helper, functional, and selected-entrypoint smoke check uses Bun's named-test reporter; output includes per-test status, timings, and pass/fail totals. Functional tests cover deterministic helpers where practical; smoke tests bundle entrypoints and parse config. They do not test live TUI behavior, provider credentials, network access, or PDF extraction.

package/extensions/opl-guardian/README.md

@@ -0,0 +1,52 @@
+# opl-guardian
+
+Prevents malformed assistant tool calls from entering Pi session history. It runs on every provider and model through Pi's `message_end` hook, removes protocol-invalid calls before Pi persists or replays them, and records each removal as JSON Lines evidence.
+
+>
+> This is the first feature that opl-guardian can do for now. If I happen to encounter another error/issue that can be (possibly) fixed via extensions, I might add that up in this extension.
+>
+
+## Commands, tools, and configuration
+
+No commands, tools, or configuration. Loading the extension is the entire interface and adds no prompt or tool-schema overhead.
+
+## What it guards
+
+A tool call is malformed when its `id` or `name` is blank after trimming whitespace. Such a record cannot be safely replayed through OpenAI-compatible tool-call APIs: a later provider request may reject it and block the session until its history is abandoned.
+
+`opl-guardian` does not reject an unfamiliar but non-empty tool name. That is a normal model/tool-resolution error, not an invalid protocol envelope.
+
+| Assistant response | Guardian behavior |
+| --- | --- |
+| No malformed calls | Leaves the response unchanged. |
+| Valid and malformed calls | Drops only malformed calls, preserves valid calls and `toolUse`, appends a diagnostic, and lets Pi execute the valid calls normally. |
+| Only malformed calls | Removes every call, returns a text-only `stop` response, and tells the user to send another prompt. |
+
+When a UI is available, every incident also produces a warning notification.
+
+## Forensic JSONL
+
+Each incident appends one JSON object to:
+
+```text
+<project cwd>/err/guardian.jsonl
+```
+
+A record includes timestamp, session ID, project CWD, provider, model, response ID when available, and the removed `toolCall` blocks. It does not log prompts, assistant text, thinking, or tool results.
+
+Tool-call arguments can still contain project paths, commands, or user text. Add `err/` to the project’s version-control ignore policy if it is not already ignored, and treat the file as local diagnostic data.
+
+If the log write fails, guardian still removes the malformed calls. The session diagnostic and UI warning report that the forensic file could not be written rather than claiming it was saved.
+
+## Architecture
+
+```text
+guardian.ts  Pure malformed-call filter and JSONL incident-record builder.
+index.ts     Pi message_end handler, project-local JSONL append, UI notification.
+```
+
+The extension has no runtime dependencies. Run its checks with:
+
+```bash
+npm run test:opl-guardian
+```

package/extensions/opl-guardian/guardian.ts

@@ -0,0 +1,70 @@
+import type { AssistantMessage, ToolCall } from "@earendil-works/pi-ai";
+
+export interface IncidentContext {
+  sessionId: string;
+  cwd: string;
+}
+
+export interface GuardianIncident {
+  timestamp: string;
+  kind: "malformed_tool_call";
+  sessionId: string;
+  cwd: string;
+  provider: string;
+  model: string;
+  responseId?: string;
+  action: "dropped";
+  removedToolCalls: ToolCall[];
+}
+
+export interface GuardResult {
+  message: AssistantMessage;
+  removedToolCalls: ToolCall[];
+}
+
+function hasValue(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function isMalformedToolCall(block: unknown): block is ToolCall {
+  if (!block || typeof block !== "object" || (block as { type?: unknown }).type !== "toolCall") {
+    return false;
+  }
+  const toolCall = block as ToolCall;
+  return !hasValue(toolCall.id) || !hasValue(toolCall.name);
+}
+
+export function guardAssistantMessage(message: AssistantMessage): GuardResult | undefined {
+  const removedToolCalls = message.content.filter(isMalformedToolCall);
+  if (removedToolCalls.length === 0) return undefined;
+
+  const content = message.content.filter((block) => !isMalformedToolCall(block));
+  const hasValidToolCall = content.some((block) => block.type === "toolCall");
+
+  return {
+    removedToolCalls,
+    message: {
+      ...message,
+      content,
+      stopReason: hasValidToolCall ? "toolUse" : "stop",
+    },
+  };
+}
+
+export function buildIncidentRecord(
+  message: AssistantMessage,
+  context: IncidentContext,
+  removedToolCalls: ToolCall[],
+): GuardianIncident {
+  return {
+    timestamp: new Date(message.timestamp).toISOString(),
+    kind: "malformed_tool_call",
+    sessionId: context.sessionId,
+    cwd: context.cwd,
+    provider: message.provider,
+    model: message.model,
+    ...(message.responseId ? { responseId: message.responseId } : {}),
+    action: "dropped",
+    removedToolCalls,
+  };
+}

package/extensions/opl-guardian/index.ts

@@ -0,0 +1,81 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { appendFile, chmod, mkdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  buildIncidentRecord,
+  guardAssistantMessage,
+  type GuardianIncident,
+} from "./guardian.js";
+
+const LOG_PATH = join("err", "guardian.jsonl");
+
+export async function appendIncident(cwd: string, incident: GuardianIncident): Promise<void> {
+  const directory = join(cwd, "err");
+  const path = join(cwd, LOG_PATH);
+  await mkdir(directory, { recursive: true });
+
+  let existed = true;
+  try {
+    await stat(path);
+  } catch {
+    existed = false;
+  }
+
+  await appendFile(path, `${JSON.stringify(incident)}\n`, "utf8");
+  if (!existed && process.platform !== "win32") {
+    await chmod(path, 0o600).catch(() => {});
+  }
+}
+
+function diagnostic(removed: number, logError?: unknown): string {
+  if (logError) {
+    const detail = logError instanceof Error ? logError.message : String(logError);
+    return `[opl-guardian] Dropped malformed provider tool call(s), but could not write err/guardian.jsonl: ${detail}.`;
+  }
+  return `[opl-guardian] Dropped ${removed} malformed provider tool call(s). Details: err/guardian.jsonl.`;
+}
+
+function appendDiagnostic(message: AssistantMessage, text: string, invalidOnly: boolean): AssistantMessage {
+  const content = invalidOnly
+    ? [{ type: "text" as const, text: `${text} No tool was executed; send another prompt to continue.` }]
+    : [...message.content, { type: "text" as const, text }];
+  return { ...message, content, stopReason: invalidOnly ? "stop" : "toolUse" };
+}
+
+export async function guardMessageEnd(
+  message: AssistantMessage,
+  context: { cwd: string; sessionId: string },
+): Promise<{ message: AssistantMessage; diagnostic: string } | undefined> {
+  const guarded = guardAssistantMessage(message);
+  if (!guarded) return undefined;
+
+  let logError: unknown;
+  try {
+    await appendIncident(context.cwd, buildIncidentRecord(message, context, guarded.removedToolCalls));
+  } catch (error) {
+    logError = error;
+  }
+
+  const invalidOnly = !guarded.message.content.some((block) => block.type === "toolCall");
+  const notice = diagnostic(guarded.removedToolCalls.length, logError);
+  return {
+    message: appendDiagnostic(guarded.message, notice, invalidOnly),
+    diagnostic: notice,
+  };
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("message_end", async (event, ctx) => {
+    if (event.message.role !== "assistant") return;
+    const guarded = await guardMessageEnd(event.message, {
+      cwd: ctx.cwd,
+      sessionId: ctx.sessionManager.getSessionId(),
+    });
+    if (!guarded) return;
+
+    ctx.ui?.notify(guarded.diagnostic, "warning");
+    return { message: guarded.message };
+  });
+}

package/extensions/opl-modes/README.md

@@ -11,7 +11,7 @@ Unified mode manager for Pi. It provides normal, read-only chat, read-only plann
 - `--chat` and `--plan` start Pi in the corresponding read-only mode.
 - The configured cycle shortcut rotates through enabled visible modes. Execute mode is excluded from cycling because it requires an active plan. The default `shift+tab` is also Pi's built-in `app.thinking.cycle`, so both fire on one press; rebind either action in `~/.pi/agent/keybindings.json` (or pick another `shortcuts.cycleMode`) if you want them separate.
 
-Plans are Markdown files under `.pi/plans/` with the `plan-` filename prefix. A plan name must contain at least one letter or digit, so `/plan .` or `/plan --` is rejected instead of producing an untitled `plan-.md`. `plan_complete` is available in execute mode and in any mode that sets `allowPlanComplete`. On completion, the plan file is deleted when `cleanup.cleanupOnComplete` is enabled. If execution ends without `plan_complete`, execute mode is exited automatically — but only when a turn actually finished: an aborted (ESC) or errored turn keeps execute mode active so the plan can be resumed.
+Plans are Markdown files under `.pi/plans/` with the `plan-` filename prefix. A plan name must contain at least one letter or digit, so `/plan .` or `/plan --` is rejected instead of producing an untitled `plan-.md`. `plan_complete` is available in execute mode and in any mode that sets `allowPlanComplete`. On completion, the plan file is deleted when `cleanup.cleanupOnComplete` is enabled. If execution ends without `plan_complete`, execute mode is exited automatically at Pi's `agent_before_settle` boundary (added in Pi 0.87.0) — but only when the run settled as `completed`: an aborted (ESC) or errored run keeps execute mode active so the plan can be resumed. On Pi < 0.87.0 this auto-exit is unavailable because the boundary is never emitted; `plan_complete` still exits the mode on any version.
 
 ## Extension features
 

package/extensions/opl-modes/index.ts

@@ -23,6 +23,7 @@ import type {
   ToolCallEventResult,
   ToolResultEvent,
   AgentEndEvent,
+  AgentBeforeSettleEvent,
 } from "@earendil-works/pi-coding-agent";
 import { DynamicBorder } from "@earendil-works/pi-coding-agent";
 import type { Model } from "@earendil-works/pi-ai";
@@ -668,26 +669,23 @@ export default function modeSwitcher(pi: ExtensionAPI) {
     enterOffMode(ctx, "Plan implemented. Plan mode OFF.");
   });
 
-  // ─── Event: agent_end (extract plan text in PLAN mode; auto-exit execute) ───
-
-  pi.on("agent_end", async (event: AgentEndEvent, ctx: ExtensionContext) => {
-    // If plan_complete was never called, exit execute mode automatically.
-    // (If it was called, mode is already "off" here — this check is a no-op.)
-    if (getMode() === "execute") {
-      // An aborted turn (ESC) is a pause, not a finished execution: stay in execute mode
-      // so the plan can be resumed instead of silently dropping out mid-plan. Pi emits an
-      // assistant message with stopReason "aborted" even when the abort lands before the
-      // first token, so there is always a message to read here.
-      const lastAssistant = [...event.messages].reverse().find((m) => m.role === "assistant") as
-        | { stopReason?: string }
-        | undefined;
-      // Only a turn that actually finished counts as done: "aborted"/"error" (and a missing
-      // assistant message) are pauses, so execute mode survives ESC and provider failures.
-      const reason = lastAssistant?.stopReason;
-      if (reason && reason !== "aborted" && reason !== "error") enterOffMode(ctx, "Execution complete. Mode OFF.");
-      return;
+  // ─── Event: agent_before_settle (auto-exit execute when the run is truly done) ───
+
+  // Pi 0.87 boundary: fires after any automatic retry, compaction-and-retry, or queued
+  // follow-up work, so execute mode is not dropped mid-plan at an intermediate agent_end.
+  pi.on("agent_before_settle", async (event: AgentBeforeSettleEvent, ctx: ExtensionContext) => {
+    // If plan_complete was never called, exit execute mode automatically once Pi has fully
+    // settled. (If it was called, mode is already "off" here — this check is a no-op.)
+    // "aborted" (ESC) and "error" (provider failure) are pauses, not finished executions;
+    // only a completed run exits execute mode.
+    if (getMode() === "execute" && event.outcome === "completed") {
+      enterOffMode(ctx, "Execution complete. Mode OFF.");
     }
+  });
+
+  // ─── Event: agent_end (extract plan text in PLAN mode) ───
 
+  pi.on("agent_end", async (event: AgentEndEvent, ctx: ExtensionContext) => {
     if (getMode() !== "plan") return;
     if (!ctx.hasUI) return;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlines/opl-pi-sht",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "opl-pi-sht (shouldHaveThat) Pi coding-agent extension kit: token-efficient context, safe modes, fingerprinted /init, model benchmarking, web access, and browser automation.",
   "repository": {
     "type": "git",
@@ -40,9 +40,10 @@
   },
   "type": "module",
   "scripts": {
-    "test": "npm run test:opl-browser && npm run test:opl-footer && npm run test:opl-init && npm run test:opl-input && npm run test:opl-modes && npm run test:opl-questionnaire && npm run test:opl-todo && npm run test:opl-webaccess && npm run test:opl-simplebench && npm run test:opl-ctxtrim",
+    "test": "npm run test:opl-browser && npm run test:opl-footer && npm run test:opl-guardian && npm run test:opl-init && npm run test:opl-input && npm run test:opl-modes && npm run test:opl-questionnaire && npm run test:opl-todo && npm run test:opl-webaccess && npm run test:opl-simplebench && npm run test:opl-ctxtrim",
     "test:opl-browser": "bun test tests/opl-browser-helpers.test.mjs && OPL_EXTENSION=opl-browser bun test tests/extension-smoke.test.mjs",
     "test:opl-footer": "bun test tests/opl-footer-helpers.test.mjs && OPL_EXTENSION=opl-footer bun test tests/extension-smoke.test.mjs",
+    "test:opl-guardian": "bun test tests/opl-guardian.test.mjs && OPL_EXTENSION=opl-guardian bun test tests/extension-smoke.test.mjs",
     "test:opl-init": "bun test tests/opl-init-crawl.test.mjs tests/opl-init-fingerprint.test.mjs tests/opl-init-packet.test.mjs && OPL_EXTENSION=opl-init bun test tests/extension-smoke.test.mjs",
     "test:opl-input": "bun test tests/opl-input-style.test.mjs && OPL_EXTENSION=opl-input bun test tests/extension-smoke.test.mjs",
     "test:opl-modes": "bun test tests/opl-modes-helpers.test.mjs tests/opl-modes-lifecycle.test.mjs && OPL_EXTENSION=opl-modes bun test tests/extension-smoke.test.mjs",