@taylorsatula/pi-timestamp 0.1.0 → 0.2.1

package/README.md

@@ -4,31 +4,47 @@ Timestamp injection extension for [Pi](https://pi.dev) — the model always know
 
 ## What it does
 
-Hooks `before_provider_request` and appends a synthetic tool-call pair to the outgoing message list, carrying the current local wall-clock time:
-
-```jsonc
-[
-  {
-    "role": "assistant",
-    "tool_calls": [
-      {
-        "id": "ts_1756220400000",
-        "type": "function",
-        "function": { "name": "__timestamp", "arguments": "{\"timestamp\":\"[3:00pm - 8/26/25]\"}" }
-      }
-    ]
-  },
-  { "role": "tool", "tool_call_id": "ts_1756220400000", "content": "ok" }
-]
-```
-
-Injection happens only at **turn boundaries**, not on every provider call:
+Hooks `before_provider_request` and appends the current local wall-clock time as plain text
+to the tail of the last message:
 
-- Last message is a **user message** → inject.
-- Last message is an **assistant message with text content** (a vocalization between tool steps) → inject.
-- Last message is an assistant message with only `tool_calls`, or a tool result (mid-turn churn) → skip.
+```
+They're injected poorly if they're that annoying.
+[11:34pm - 9/1/26]
+```
 
-This keeps the timestamp fresh each time control returns to the user-facing side of the loop, without spamming intermediate tool-loop requests.
+Injection happens only at **turn boundaries**, never mid-tool-loop, and handles both wire
+formats the hook can deliver (the payload is the provider-serialized request body, which
+differs per API):
+
+- **Chat Completions / Anthropic** (conversation under `messages`): last message is a
+  **user message** → append the timestamp to its content. Last message is an
+  **assistant message with text content** (a vocalization between tool steps) → append
+  to its content. Last message is an assistant message carrying `tool_calls`, a tool
+  result, or an Anthropic user message containing a `tool_result` block (that API's
+  tool-result encoding) → skip.
+- **OpenAI Responses API** (conversation under `input`, typed items): last item is a
+  user item → append to its content blocks. Last item is an assistant `message` item
+  (vocalization) → append to its `output_text` blocks. Last item is a `function_call` or
+  `function_call_output` item → skip.
+
+## Why plain-text tail append (design notes)
+
+- **Cache safety.** The tail of the message list is the only cache-safe injection point:
+  mutating the system prompt would invalidate the KV-cache prefix on every request; a
+  tail mutation re-processes only the last message. The system prompt is never touched.
+- **No synthetic tool calls.** Appending after an assistant message that carries a
+  `tool_call` would require fabricating a tool-call pair (a call must be answered by its
+  result) — so those positions are simply never injected. In the positions that are
+  injected, no disguise is needed, so none is used. The model never appears to call a
+  nonexistent tool, and transcripts never render phantom calls.
+- **Idempotent.** A previously appended tag is stripped before the fresh one is written,
+  so re-fires and retries cannot stack timestamps.
+- **Content-shape aware.** String content concatenates directly; block-array content
+  (Anthropic-shaped) appends into or after the last text block; unknown shapes are left
+  untouched rather than guessed at.
+- **Wire-format aware.** Chat Completions/Anthropic payloads (`messages`) and OpenAI
+  Responses payloads (`input`, typed items) are both handled; any other payload shape
+  passes through untouched.
 
 ## Installation
 
@@ -46,9 +62,18 @@ Or add to `~/.pi/agent/settings.json` under `packages`:
 
 ## Notes
 
-- Timestamps use the machine's **local time**, formatted `h:mmam/pm - M/D/YY` (e.g. `[3:07pm - 8/26/25]`).
-- No tools, commands, shortcuts, or settings are registered — the extension is invisible except for the injected messages.
-- The injected pair is added to the outgoing payload only; it is not persisted to the session transcript.
+- Timestamps use the machine's **local time**, formatted `h:mmam/pm - M/D/YY`
+  (e.g. `[3:07pm - 8/26/25]`).
+- No tools, commands, shortcuts, or settings are registered — the extension is invisible
+  except for the appended tag.
+- The tag is added to the outgoing payload only; it is not persisted to the session
+  transcript.
+- Version 0.2.0 changed the mechanism (plain-text tail append replacing the synthetic
+  tool-call pair). Sessions started before the upgrade may still show one old-style pair
+  until restart.
+- Version 0.2.1 fixed a crash on OpenAI Responses-API models (`before_provider_request`
+  payloads carry the conversation under `input`, not `messages`) and added
+  Anthropic `tool_result` skipping.
 
 ## Development
 

package/extensions/timestamp.ts

@@ -1,5 +1,31 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
+// Cache-correct tail injection: mutating the system prompt would invalidate the
+// KV-cache prefix on every request; the last message is the only cache-safe
+// injection point, and only when no tool call is pending.
+//
+// Design:
+//   - Inject into user messages and text-only assistant vocalizations by
+//     appending plain text to the message content. No fabricated tool-call
+//     pair — the pair disguise is only structurally required in tool-call
+//     positions, which we never inject into.
+//   - Never inject after an assistant message carrying tool_calls (appending
+//     there would require wedging a pair between the call and its result) and
+//     never after tool results (mid-loop churn).
+//   - Idempotent per request: a previously appended tag is stripped before the
+//     fresh one is written.
+//
+// Payload shapes (before_provider_request delivers the provider-serialized
+// request body, which differs per API):
+//   - Chat Completions / Anthropic: conversation lives under `messages`.
+//   - OpenAI Responses API: conversation lives under `input`, with typed items
+//     (input_text / output_text content blocks, function_call and
+//     function_call_output tool traffic) instead of chat messages.
+
+type Rec = Record<string, unknown>;
+
+const TS_STRIP = /\n\[\d{1,2}:\d{2}(am|pm) - \d{1,2}\/\d{1,2}\/\d{2}\]\s*$/;
+
 function formatTimestamp(): string {
   const now = new Date();
   let hours = now.getHours();
@@ -13,52 +39,79 @@ function formatTimestamp(): string {
   return `[${hours}:${String(minutes).padStart(2, "0")}${ampm} - ${month}/${day}/${year}]`;
 }
 
-function shouldInject(msgs: Array<Record<string, unknown>>): boolean {
-  const last = msgs[msgs.length - 1];
-  if (!last) return false;
+// Chat Completions / Anthropic shape: payload.messages
+// user: { role: "user", content: string | blocks }
+// assistant vocalization: { role: "assistant", content: string | blocks, no tool_calls }
+// assistant tool call: { role: "assistant", tool_calls: [...] }
+// Anthropic tool results arrive as user messages containing a tool_result
+// content block; treat them as mid-loop traffic, not turn boundaries.
 
-  // User message → inject
-  if (last.role === "user") return true;
-
-  // Assistant with text content (vocalization) → inject
-  // Assistant with only tool_calls (intermediate) → skip
+function chatShouldInject(last: Rec): boolean {
+  if (last.role === "user") {
+    const content = last.content;
+    if (Array.isArray(content) && content.some((b) => (b as Rec).type === "tool_result")) {
+      return false;
+    }
+    return true;
+  }
   if (last.role === "assistant") {
     const hasToolCalls = Array.isArray(last.tool_calls) && last.tool_calls.length > 0;
     const hasContent = last.content != null && last.content !== "";
-    return !hasToolCalls && hasContent;
+    return !hasToolCalls && hasContent; // vocalization → inject; tool call → never
   }
-
-  // Tool results → skip (intermediate)
   return false;
 }
 
+// OpenAI Responses shape: payload.input
+// user: { role: "user", content: [{ type: "input_text", text }, ...] }
+// vocalization: { type: "message", role: "assistant", content: [{ type: "output_text", ... }] }
+// tool call: { type: "function_call", ... } / result: { type: "function_call_output", ... }
+
+function responsesShouldInject(last: Rec): boolean {
+  if (last.role === "user") return true;
+  if (last.type === "message" && last.role === "assistant") {
+    return Array.isArray(last.content) && last.content.length > 0;
+  }
+  return false; // function_call / function_call_output → mid-loop, skip
+}
+
 export default function (pi: ExtensionAPI) {
   pi.on("before_provider_request", (event) => {
-    const payload = event.payload as Record<string, unknown>;
-    const msgs = payload.messages as Array<Record<string, unknown>>;
+    const payload = event.payload as Rec;
+    const isResponses = Array.isArray(payload.input);
+    const items = isResponses
+      ? (payload.input as Rec[])
+      : Array.isArray(payload.messages)
+        ? (payload.messages as Rec[])
+        : undefined;
+    if (!items) return; // unknown payload shape → leave untouched
 
-    if (!shouldInject(msgs)) return;
+    const last = items[items.length - 1];
+    if (!last) return;
+    if (!(isResponses ? responsesShouldInject(last) : chatShouldInject(last))) return;
 
-    const timestamp = formatTimestamp();
-    const callId = `ts_${Date.now()}`;
+    const ts = `\n${formatTimestamp()}`;
 
-    msgs.push(
-      {
-        role: "assistant",
-        tool_calls: [
-          {
-            id: callId,
-            type: "function",
-            function: { name: "__timestamp", arguments: JSON.stringify({ timestamp }) },
-          },
-        ],
-      },
-      {
-        role: "tool",
-        tool_call_id: callId,
-        content: "ok",
-      },
-    );
+    if (typeof last.content === "string") {
+      last.content = last.content.replace(TS_STRIP, "") + ts;
+    } else if (Array.isArray(last.content)) {
+      // Provider-shaped block arrays: normalize the last text-bearing block in
+      // place, or append a typed text block when none exists.
+      const blocks = [...(last.content as Rec[])];
+      const idx = blocks.length - 1;
+      const lastBlock = blocks[idx] as { text?: unknown } | undefined;
+      if (lastBlock && typeof lastBlock.text === "string") {
+        blocks[idx] = { ...lastBlock, text: lastBlock.text.replace(TS_STRIP, "") + ts };
+      } else if (isResponses && last.role === "assistant") {
+        blocks.push({ type: "output_text", text: ts, annotations: [] });
+      } else if (isResponses) {
+        blocks.push({ type: "input_text", text: ts });
+      } else {
+        blocks.push({ type: "text", text: ts });
+      }
+      last.content = blocks;
+    }
+    // Non-string, non-array content shapes: leave untouched rather than guess.
 
     return event.payload;
   });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@taylorsatula/pi-timestamp",
-  "version": "0.1.0",
-  "description": "Timestamp injection extension for Pi — appends the current wall-clock time as a synthetic tool-call pair to every provider request at turn boundaries, so the model always knows what time it is.",
+  "version": "0.2.1",
+  "description": "Timestamp injection extension for Pi — appends the current wall-clock time to the tail of user messages and vocalizations just-in-time (cache-safe, no synthetic tool calls), so the model always knows what time it is.",
   "keywords": [
     "pi-package"
   ],