@openlines/opl-pi-sht 0.2.1 → 0.2.2

package/README.md

@@ -76,6 +76,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`.                                                                            |
@@ -107,6 +108,7 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 - **`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.
 ![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 +139,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 +163,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 +221,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlines/opl-pi-sht",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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",