@taylorsatula/pi-timestamp 0.1.0 → 0.2.0

package/README.md

@@ -4,31 +4,37 @@ 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:
+
+- 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`, or a tool result (mid-turn
+  churn) → 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.
 
 ## Installation
 
@@ -46,9 +52,15 @@ 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.
 
 ## Development
 

package/extensions/timestamp.ts

@@ -1,5 +1,22 @@
 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.
+
+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 +30,46 @@ function formatTimestamp(): string {
   return `[${hours}:${String(minutes).padStart(2, "0")}${ampm} - ${month}/${day}/${year}]`;
 }
 
-function shouldInject(msgs: Array<Record<string, unknown>>): boolean {
+function injectable(msgs: Array<Record<string, unknown>>): boolean {
   const last = msgs[msgs.length - 1];
   if (!last) return false;
 
-  // User message → inject
   if (last.role === "user") return true;
 
-  // Assistant with text content (vocalization) → inject
-  // Assistant with only tool_calls (intermediate) → skip
   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;
+  return false; // tool results → 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>>;
+    if (!injectable(msgs)) return;
 
-    if (!shouldInject(msgs)) return;
-
-    const timestamp = formatTimestamp();
-    const callId = `ts_${Date.now()}`;
+    const ts = `\n${formatTimestamp()}`;
+    const last = msgs[msgs.length - 1];
 
-    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 (e.g. Anthropic): normalize the last
+      // text block in place, or append a text block when none exists.
+      const blocks = [...(last.content as Array<Record<string, unknown>>)];
+      const idx = blocks.length - 1;
+      const lastBlock = blocks[idx] as { type?: string; text?: string } | undefined;
+      if (lastBlock && lastBlock.type === "text" && typeof lastBlock.text === "string") {
+        blocks[idx] = { ...lastBlock, text: lastBlock.text.replace(TS_STRIP, "") + 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.0",
+  "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"
   ],