pi-tool-duration 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.3.0] - 2026-09-21
+
+### Changed
+
+- Annotate every tool result by default with `[host tool-call elapsed: Xs]`. Set `PI_TOOL_DURATION_THRESHOLD_MS=1000` to retain slow/failed-only reporting.
+- Require Pi 0.87.0 or later, using the same native extension APIs on official Pi and the maintained fork.
+- Resolve timings through a stateless backward ancestry lookup instead of rebuilding the complete historical timing map for every request.
+
+### Fixed
+
+- Preserve prompt and tool updates in model context so duration annotations do not collapse the reusable request prefix.
+- Associate timing with the finalized result when a later extension replaces its timestamp, preserving existing saved timing records.
+
+### Tests
+
+- Exercise native Responses serialization, dynamic prompt/tool prefixes, and finalized timestamps.
+- Verify actual timed results through disk restoration and maintained-fork checkpoints.
+
 ## [0.2.3] - 2026-09-18
 
 ### Fixed

package/README.md

@@ -1,81 +1,83 @@
 # pi-tool-duration
 
-Appends `[duration: Xs]` to slow Pi tool results so the model can tell when a tool actually took time.
+Makes host-observed tool-call timing visible to the model without changing Pi's terminal output.
 
 ```text
 hi
-[duration: 5.0s]
+[host tool-call elapsed: 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.
+Every completed tool result is annotated by default. An optional threshold limits successful-call annotations; failed calls are always annotated.
 
 ## How it works
 
-The extension measures from Pi's `tool_execution_start` through `tool_execution_end`. When elapsed time is at or above the configured threshold, or Pi marks the result as failed, it saves the timing in a hidden session entry. Before each model request, it appends one text block to that request's copy of the tool result:
-
-```text
-[duration: 5.0s]
-```
+The extension measures from Pi's `tool_execution_start` through `tool_execution_end` using a monotonic clock. It saves the timing in a hidden session entry and appends one text block to the model-request copy of the result. Durations are rounded to tenths of a second.
 
-Compaction input copies put timing before the tool output so it survives Pi's truncation of long results. Recorded tool output stays unchanged, including after reload, resume, and branch navigation. Timings remain available to the model across those transitions without duplicating Pi's native TUI timing such as `Took 5.0s`.
+The measurement includes preflight and result processing. In a parallel batch, it can include time spent preparing later siblings, but stops when this call finishes even if another call continues. For a tool that launches a background job, it measures the launch call. Parallel durations are not additive task elapsed time.
 
-Markers already saved as tool text by versions through 0.2.1 remain unchanged. They cannot be safely distinguished from genuine tool output with the same text.
+Recorded tool content, details, images, and native terminal rendering stay unchanged. Timings survive reload, resume, forks, branch navigation, and retained compaction history. Request-time lookup walks backward only as far as needed to find the visible results and their preceding timing records; older or unidentifiable results can require a longer walk.
 
-Scope: Pi tools that emit tool execution events, including built-ins and extension tools. Direct `!` / `!!` shell commands and RPC `bash` command messages are not tool results and are not annotated.
+Compaction input copies put timing before tool output so Pi's truncation preserves it in the summarizer's input. Generated summaries may omit individual timings. Native branch summaries exclude tool results. Historical markers keep their original text, and tool output resembling a marker is never removed or rewritten.
 
-Pi starts these timers during sequential tool-call preflight. In a parallel batch, a call's elapsed time can therefore include time spent preparing later siblings. This mirrors Pi's TUI timing.
+Scope: built-in and extension tools that emit Pi execution events. Direct `!` / `!!` shell commands and RPC `bash` command messages are not tool results and are not annotated.
 
 ## Install
 
-Requires Pi 0.84.0 or later.
+Requires Pi **0.87.0 or later**. Tested against official Pi and the maintained `fitchmultz/pi` fork.
 
 ```bash
-pi install .                         # local, global settings
-pi install -l --approve .            # local, project settings
-pi install npm:pi-tool-duration      # published package
+pi install npm:pi-tool-duration
 ```
 
-## Try without installing
-
-From this repo:
+For local development:
 
 ```bash
-pi --no-extensions -e .
-# or
-pi --no-extensions -e ./extensions/tool-duration/index.ts
+pi install .                         # global settings
+pi install -l --approve .            # project settings
+pi --no-extensions -e .              # try without installing
 ```
 
-`--no-extensions` prevents a duplicate flag conflict when another copy is already installed.
+`--no-extensions` prevents a duplicate flag conflict when another copy is already installed. Restart Pi after updating extension code; `/reload` reinitializes the loaded code but does not replace it.
 
 ## Configure
 
-Default threshold: `1000` ms.
+Default threshold: **0 ms**, including fast calls.
 
 ```bash
-PI_TOOL_DURATION_THRESHOLD_MS=0 pi --no-extensions -e .   # annotate every tool result
-pi --no-extensions -e . --tool-duration-threshold-ms 500  # annotate tools taking >= 500ms
+# Restore slow/failed-only reporting:
+PI_TOOL_DURATION_THRESHOLD_MS=1000 pi --no-extensions -e .
+
+# CLI value takes precedence:
+pi --no-extensions -e . --tool-duration-threshold-ms 500
 ```
 
-Invalid values are ignored. An invalid CLI value falls through to the environment value; an invalid environment value falls back to the default.
+Invalid CLI values fall through to the environment value; invalid environment values fall back to zero. A successful result below a configured threshold stays unchanged. Missing timing does not establish a zero-duration call.
+
+## GPT-6 Astra
+
+Use Pi's native OpenAI or OpenAI Codex Responses provider. The extension uses `context_with_system` to preserve the positions of prompt and tool updates, allowing native caching and incremental requests to work.
+
+Prefer Pi's built-in model definitions. To adjust a model's limits, use [`modelOverrides`](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md#per-model-overrides), which preserves native compatibility metadata. A same-ID entry in `models` replaces that metadata.
+
+Transport selection, reasoning settings, asynchronous tool execution, and steering remain Pi's responsibility. The extension does not alter provider requests or add model instructions.
 
 ## Verify
 
-In a session running the extension, ask Pi to use bash:
+Ask Pi to run a tool, for example:
 
 ```text
-Use bash to run: sleep 5; echo hi
+Use bash to run: sleep 1; echo hi
 ```
 
-The model sees:
+The model receives the output plus a host timing marker. Pi's terminal retains its native rendering.
 
-```text
-hi
-[duration: 5.0s]
-```
+## Development
+
+Run `npm ci --ignore-scripts` and `npm run check:compat` for typechecking, unit/native runtime tests, and a pack dry-run. There is no production build or `prepare` step. The development host is pinned to official `0.87.0`; CI separately qualifies official Pi and the maintained fork. The host-provided Pi peer stays wildcard and optional rather than bundling a runtime.
+
+Runtime tests use the installed host's manifest `bin.pi` entry and a local scripted Responses provider in an isolated HOME. `PI_HOST_CLI`, `PI_COMPAT_EXPECTED_VERSION`, and `PI_COMPAT_EXPECTED_PACKAGE_DIR` can assert the selected graph.
 
-A fast successful tool below the threshold stays unchanged. A failed tool result delivered to the model is always annotated, even below the threshold.
+The restoration test uses the installed host by default; `PI_HOST_INDEX` can select another host's absolute `dist/index.js`. It executes a timed tool and verifies reload plus separate-process disk restoration on both hosts. Native checkpoint restoration also runs when available and is required when `PI_COMPAT_HOST=fork` or `PI_REQUIRE_CHECKPOINT=1`. These tests use local scripted model completions without provider network calls or credentials.
 
 ## License
 

package/extensions/tool-duration/index.ts

@@ -1,13 +1,12 @@
 /**
  * pi-tool-duration
  *
- * Appends `[duration: Xs]` to slow or failed tool messages 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.
+ * Adds host-observed tool-call timing to model-request copies without
+ * changing recorded tool output or Pi's native terminal rendering.
  */
-import type { ContextEvent, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ContextWithSystemEvent, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-const DEFAULT_THRESHOLD_MS = 1000;
+const DEFAULT_THRESHOLD_MS = 0;
 const TIMING_ENTRY = "pi-tool-duration";
 
 type SavedTiming = { toolCallId: string; timestamp: number; duration: string };
@@ -27,26 +26,51 @@ function thresholdMs(pi: ExtensionAPI): number {
   );
 }
 
+function timingKey(message: { timestamp: number; toolCallId: string }): string {
+  return `${message.timestamp}:${message.toolCallId}`;
+}
+
 function withDurations(
-  messages: ContextEvent["messages"],
+  messages: ContextWithSystemEvent["messages"],
   ctx: ExtensionContext,
   position: "append" | "prepend" = "append",
 ) {
+  const remaining = new Set(messages.filter((message) => message.role === "toolResult").map(timingKey));
+  if (!remaining.size) return messages;
+
   const saved = new Map<string, string>();
-  for (const entry of ctx.sessionManager.getBranch()) {
-    if (entry.type !== "custom" || entry.customType !== TIMING_ENTRY) continue;
-    const timing = entry.data as SavedTiming | undefined;
-    if (
-      typeof timing?.toolCallId !== "string" ||
-      typeof timing.timestamp !== "number" ||
-      typeof timing.duration !== "string"
-    ) continue;
-    saved.set(`${timing.timestamp}:${timing.toolCallId}`, timing.duration);
+  let pending: { key: string; toolCallId: string } | undefined;
+  // ponytail: old or unknown results can scan the full ancestry; native timing metadata would remove this join.
+  for (let id = ctx.sessionManager.getLeafId(); id && remaining.size;) {
+    const entry = ctx.sessionManager.getEntry(id);
+    if (!entry) break;
+    id = entry.parentId;
+    if (entry.type === "message") {
+      if (pending) {
+        remaining.delete(pending.key);
+        pending = undefined;
+        if (!remaining.size) break;
+      }
+      if (entry.message.role === "toolResult" && remaining.has(timingKey(entry.message))) {
+        pending = { key: timingKey(entry.message), toolCallId: entry.message.toolCallId };
+      }
+    } else if (pending && entry.type === "custom" && entry.customType === TIMING_ENTRY) {
+      const timing = entry.data as SavedTiming | undefined;
+      if (
+        typeof timing?.toolCallId !== "string" ||
+        typeof timing.timestamp !== "number" ||
+        typeof timing.duration !== "string"
+      ) continue;
+      // The following result's timestamp may have been replaced by another message_end handler.
+      if (timing.toolCallId === pending.toolCallId) saved.set(pending.key, timing.duration);
+      remaining.delete(pending.key);
+      pending = undefined;
+    }
   }
 
   return messages.map((message) => {
     if (message.role !== "toolResult") return message;
-    const duration = saved.get(`${message.timestamp}:${message.toolCallId}`);
+    const duration = saved.get(timingKey(message));
     if (!duration) return message;
     const marker = { type: "text" as const, text: duration };
     return {
@@ -77,7 +101,7 @@ export default function (pi: ExtensionAPI) {
 
     const ms = performance.now() - startedAt;
     if (!event.isError && ms < thresholdMs(pi)) return;
-    durations.set(event.toolCallId, `[duration: ${(ms / 1000).toFixed(1)}s]`);
+    durations.set(event.toolCallId, `[host tool-call elapsed: ${(ms / 1000).toFixed(1)}s]`);
   });
 
   pi.on("message_end", (event) => {
@@ -94,7 +118,7 @@ export default function (pi: ExtensionAPI) {
     });
   });
 
-  pi.on("context", (event, ctx) => ({ messages: withDurations(event.messages, ctx) }));
+  pi.on("context_with_system", (event, ctx) => ({ messages: withDurations(event.messages, ctx) }));
 
   pi.on("session_before_compact", ({ preparation }, ctx) => {
     // Native summarization bypasses context hooks and truncates tool text from the end.
@@ -108,7 +132,6 @@ export default function (pi: ExtensionAPI) {
     durations.clear();
   };
   pi.on("session_start", clearTimings);
-  pi.on("session_shutdown", clearTimings);
   pi.on("agent_end", clearTimings);
   pi.on("agent_settled", clearTimings);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-tool-duration",
-  "version": "0.2.3",
-  "description": "Append model-visible durations to slow Pi tool results",
+  "version": "0.3.0",
+  "description": "Make host-observed Pi tool-call timing visible to the model",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
   "license": "MIT",
@@ -31,6 +31,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "check:compat": "npm run check",
     "test": "node --test test/*.test.mjs",
     "check": "npm run typecheck && npm test && npm pack --dry-run"
   },
@@ -40,12 +41,12 @@
     ]
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.0",
+    "@earendil-works/pi-coding-agent": "0.87.0",
     "typebox": "1.3.7",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.84.0"
+    "@earendil-works/pi-coding-agent": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {