pi-tool-duration 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.0] - 2026-06-24
+
+### Added
+
+- Initial `pi-tool-duration` package.
+- Appends `[duration: Xs]` to model-visible Pi tool results when execution meets the configured threshold.
+- Supports `--tool-duration-threshold-ms` and `PI_TOOL_DURATION_THRESHOLD_MS` overrides.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-tool-duration contributors
+
+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,72 @@
+# pi-tool-duration
+
+Appends `[duration: Xs]` to slow Pi tool results so the model can tell when a tool actually took time.
+
+```text
+hi
+[duration: 5.0s]
+```
+
+## Why
+
+Pi already shows tool timing in the TUI (`Took Xs`), but that timing is UI-only. This extension adds the elapsed time to the model-visible tool result for slow calls.
+
+## How it works
+
+The extension matches Pi `tool_call` and `tool_result` events by `toolCallId`. When elapsed time is at or above the configured threshold, it appends one text block:
+
+```text
+[duration: 5.0s]
+```
+
+Scope: Pi tools that emit `tool_result` events, including built-ins and extension tools. Direct `!` / `!!` shell commands and RPC `bash` command messages are not tool results and are not annotated.
+
+## Install
+
+```bash
+pi install .                         # local, global settings
+pi install -l --approve .            # local, project settings
+pi install npm:pi-tool-duration      # after npm publish
+```
+
+## Try without installing
+
+From this repo:
+
+```bash
+pi -e .
+# or
+pi -e ./extensions/tool-duration/index.ts
+```
+
+## Configure
+
+Default threshold: `1000` ms.
+
+```bash
+PI_TOOL_DURATION_THRESHOLD_MS=0 pi -e .        # annotate every tool result
+pi -e . --tool-duration-threshold-ms 500       # annotate tools taking >= 500ms
+```
+
+Invalid threshold values fall back to the default.
+
+## Verify
+
+In a session running the extension, ask Pi to use bash:
+
+```text
+Use bash to run: sleep 5; echo hi
+```
+
+The model sees:
+
+```text
+hi
+[duration: 5.0s]
+```
+
+A fast command below the threshold stays unchanged.
+
+## License
+
+MIT

package/extensions/tool-duration/index.ts

@@ -0,0 +1,65 @@
+/**
+ * pi-tool-duration
+ *
+ * Appends `[duration: Xs]` to slow tool results so the model sees how long a
+ * call actually took. pi already measures this for the TUI ("Took Xs") but the
+ * model does not see that timing.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_THRESHOLD_MS = 1000;
+const DURATION_RE = /^\[duration: \d+(?:\.\d+)?s\]$/;
+
+function parseThreshold(value: unknown): number | undefined {
+  if (typeof value !== "string" && typeof value !== "number") return undefined;
+  if (typeof value === "string" && value.trim() === "") return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+function thresholdMs(pi: ExtensionAPI): number {
+  return (
+    parseThreshold(pi.getFlag("tool-duration-threshold-ms")) ??
+    parseThreshold(process.env.PI_TOOL_DURATION_THRESHOLD_MS) ??
+    DEFAULT_THRESHOLD_MS
+  );
+}
+
+function alreadyAnnotated(content: Array<{ type: string; text?: string }>): boolean {
+  const last = content.at(-1);
+  return last?.type === "text" && typeof last.text === "string" && DURATION_RE.test(last.text);
+}
+
+export default function (pi: ExtensionAPI) {
+  const starts = new Map<string, number>();
+
+  pi.registerFlag("tool-duration-threshold-ms", {
+    description: "Minimum tool duration in milliseconds before appending [duration: Xs] to the model-visible result",
+    type: "string",
+  });
+
+  pi.on("tool_call", async (event) => {
+    starts.set(event.toolCallId, performance.now());
+  });
+
+  pi.on("tool_result", async (event) => {
+    const startedAt = starts.get(event.toolCallId);
+    starts.delete(event.toolCallId);
+    if (startedAt === undefined) return;
+
+    const ms = performance.now() - startedAt;
+    if (ms < thresholdMs(pi) || alreadyAnnotated(event.content)) return;
+
+    return {
+      content: [
+        ...event.content,
+        { type: "text" as const, text: `[duration: ${(ms / 1000).toFixed(1)}s]` },
+      ],
+    };
+  });
+
+  const clearStarts = () => starts.clear();
+  pi.on("session_start", clearStarts);
+  pi.on("session_shutdown", clearStarts);
+  pi.on("agent_end", clearStarts);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "pi-tool-duration",
+  "version": "0.1.0",
+  "description": "Append model-visible durations to slow Pi tool results",
+  "type": "module",
+  "author": "Mitch Fultz (https://github.com/fitchmultz)",
+  "license": "MIT",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "tool-duration",
+    "observability"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fitchmultz/pi-tool-duration.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fitchmultz/pi-tool-duration/issues"
+  },
+  "homepage": "https://github.com/fitchmultz/pi-tool-duration#readme",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "extensions/tool-duration/index.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.mjs",
+    "check": "npm run typecheck && npm test && npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/tool-duration"
+    ]
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  }
+}