@signalridge/pi-worktime 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.0.0
+### Major Changes
+
+- Adopt a unified 1.0.0 across every published package.
+  
+  The version numbers no longer track their upstream forks individually; from this release each package
+  is versioned on its own merit against the Signalridge line, and 1.0.0 is the shared starting point.
+  Packages whose behavior changed in this release document that change in their own changeset entries;
+  the remainder are re-released unchanged so the whole set shares one baseline.
+- Initial release of the `@signalridge/pi-worktime` package for per-prompt, branch-scoped active worktime tracking.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tomsej
+
+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,62 @@
+# pi-worktime
+
+`@signalridge/pi-worktime` tracks active agent time for the current prompt. It
+accumulates only the spans between `agent_start` and `agent_end`, and resets when
+an accepted user message starts (`message_start` with `message.role === "user"`).
+Preflight `input` is intentionally not used, so rejected or handled input does
+not erase the current worktime. The current value is exposed through Pi's
+namespaced `worktime:update` event.
+
+In TUI sessions it owns the `worktime` status key with a compact value such as
+`2m 5s`. The `/worktime` command reports the same value when Pi provides a UI.
+There is no persistence or settings file; print, JSON, and RPC sessions still
+receive validated event-bus updates without invoking TUI-only status APIs.
+
+## Install
+
+```bash
+pi install npm:@signalridge/pi-worktime
+```
+
+## Use from this checkout
+
+From the repository root:
+
+```bash
+pi -e ./packages/pi-worktime
+```
+
+## Public imports
+
+The package exports typed source entrypoints for both extension loading and
+library consumers:
+
+```ts
+import worktime, { WORKTIME_UPDATE_EVENT } from "@signalridge/pi-worktime";
+import {
+  parseWorktimeUpdatePayload,
+  type WorktimeUpdatePayload,
+} from "@signalridge/pi-worktime/events";
+```
+
+## Event contract
+
+Consumers can subscribe to `worktime:update` through `pi.events`. Payloads are
+immutable exact objects of the following shape:
+
+```ts
+{ ms: number; running: boolean }
+```
+
+`ms` is finite and nonnegative. `parseWorktimeUpdatePayload()` returns a fresh
+frozen normalized payload or `undefined`; `isWorktimeUpdatePayload()` validates
+without executing accessors and rejects proxies, extra keys, and invalid values.
+
+## Provenance
+
+The active-span behavior and compact formatter are adapted from tomsej's
+MIT-licensed `extensions/worktime` extension in
+[`tomsej/pi-ext`](https://github.com/tomsej/pi-ext), original worktime commit
+`204182c`. This package is an independent TypeScript implementation with
+session-safe lifecycle handling, validated immutable events, and TUI/headless
+guards.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@signalridge/pi-worktime",
+  "version": "1.0.0",
+  "description": "Per-prompt active worktime tracking for Pi.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "worktime",
+    "active-time",
+    "productivity"
+  ],
+  "piExtension": {
+    "lifecycle": "stable"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.7",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@types/node": "^24.10.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.0.18"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/signalridge/pi-extensions",
+    "directory": "packages/pi-worktime"
+  },
+  "homepage": "https://github.com/signalridge/pi-extensions/tree/main/packages/pi-worktime",
+  "bugs": {
+    "url": "https://github.com/signalridge/pi-extensions/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./events": {
+      "types": "./src/events.ts",
+      "default": "./src/events.ts"
+    }
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "test": "vitest run test --config vitest.config.ts",
+    "check": "bun run lint && bun run typecheck && bun run test",
+    "format": "biome check --write ."
+  }
+}

package/src/core.ts

@@ -0,0 +1,120 @@
+import { performance } from "node:perf_hooks";
+
+/** A clock returning a monotonic millisecond value. */
+export type WorktimeClock = () => number;
+
+export interface Worktime {
+  /** Reset accumulated active time; a running span remains running from now. */
+  reset(): void;
+  /** Start an active span. Repeated calls do not restart the span. */
+  start(): void;
+  /** End the active span. Repeated calls do not add time. */
+  end(): void;
+  /** Return the accumulated active time in milliseconds. */
+  elapsed(): number;
+  readonly running: boolean;
+}
+
+const MAX_DURATION_MS = Number.MAX_VALUE;
+
+function readClock(clock: WorktimeClock): number | undefined {
+  try {
+    const value = clock();
+    return Number.isFinite(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function clampDuration(value: number): number {
+  if (value <= 0 || Number.isNaN(value)) return 0;
+  if (value === Number.POSITIVE_INFINITY) return MAX_DURATION_MS;
+  if (!Number.isFinite(value)) return 0;
+  return value;
+}
+
+function addDurations(left: number, right: number): number {
+  const sum = left + right;
+  return Number.isFinite(sum) ? clampDuration(sum) : MAX_DURATION_MS;
+}
+
+function activeSpan(start: number | undefined, current: number | undefined): number {
+  if (start === undefined || current === undefined) return 0;
+  const difference = current - start;
+  if (difference === Number.POSITIVE_INFINITY) return MAX_DURATION_MS;
+  if (!Number.isFinite(difference) || difference <= 0) return 0;
+  return difference;
+}
+
+/**
+ * Create an active-time state machine.
+ *
+ * Time is accumulated only while running. Invalid clock samples contribute no
+ * time, and injected samples are normalized to a nondecreasing sequence so a
+ * wall-clock correction cannot make the public duration regress. The default
+ * clock is monotonic; the clock is injectable so lifecycle behavior can be
+ * deterministic in tests without replacing global time APIs.
+ */
+export function createWorktime(clock: WorktimeClock = () => performance.now()): Worktime {
+  let totalMs = 0;
+  let running = false;
+  let runStart: number | undefined;
+  let lastClockSample: number | undefined;
+
+  const readSample = (): number | undefined => {
+    const sample = readClock(clock);
+    if (sample === undefined) return undefined;
+    if (lastClockSample !== undefined && sample < lastClockSample) return lastClockSample;
+    lastClockSample = sample;
+    return sample;
+  };
+
+  return {
+    reset(): void {
+      totalMs = 0;
+      runStart = running ? readSample() : undefined;
+    },
+
+    start(): void {
+      if (running) return;
+      running = true;
+      runStart = readSample();
+    },
+
+    end(): void {
+      if (!running) return;
+      totalMs = addDurations(totalMs, activeSpan(runStart, readSample() ?? lastClockSample));
+      running = false;
+      runStart = undefined;
+    },
+
+    elapsed(): number {
+      if (!running) return totalMs;
+      const current = readSample();
+      if (runStart === undefined) {
+        // An invalid sample cannot establish a span. A later valid sample is a
+        // safe new baseline rather than an invitation to count unknown time.
+        runStart = current;
+        return totalMs;
+      }
+      return addDurations(totalMs, activeSpan(runStart, current ?? lastClockSample));
+    },
+
+    get running(): boolean {
+      return running;
+    },
+  };
+}
+
+/** Format a duration compactly as `1h 2m 3s`, `2m 3s`, or `3s`. */
+export function formatDuration(milliseconds: number): string {
+  const duration = Number.isFinite(milliseconds) && milliseconds >= 0 ? milliseconds : 0;
+  const totalSeconds = Math.floor(duration / 1000);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (hours > 0) return `${hours}h ${minutes}m ${seconds}s`;
+  if (minutes > 0) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}

package/src/events.ts

@@ -0,0 +1,69 @@
+import { types as nodeTypes } from "node:util";
+
+export const WORKTIME_UPDATE_EVENT = "worktime:update";
+
+export interface WorktimeUpdatePayload {
+  ms: number;
+  running: boolean;
+}
+
+type PlainObject = { [key: PropertyKey]: unknown };
+
+function isPlainObject(value: unknown): value is PlainObject {
+  if (typeof value !== "object" || value === null) return false;
+
+  try {
+    if (nodeTypes.isProxy(value) || Array.isArray(value)) return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeWorktimeUpdatePayload(value: unknown): WorktimeUpdatePayload | undefined {
+  if (!isPlainObject(value)) return undefined;
+
+  try {
+    const keys = Reflect.ownKeys(value);
+    if (keys.length !== 2 || !keys.includes("ms") || !keys.includes("running")) return undefined;
+
+    const milliseconds = Object.getOwnPropertyDescriptor(value, "ms");
+    const running = Object.getOwnPropertyDescriptor(value, "running");
+    if (!milliseconds || !running || !("value" in milliseconds) || !("value" in running)) return undefined;
+
+    if (
+      typeof milliseconds.value !== "number" ||
+      !Number.isFinite(milliseconds.value) ||
+      milliseconds.value < 0 ||
+      typeof running.value !== "boolean"
+    ) {
+      return undefined;
+    }
+
+    return Object.freeze({
+      ms: milliseconds.value,
+      running: running.value,
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Parse and normalize an event payload into a fresh immutable snapshot.
+ * Proxies, accessors, extra keys, and invalid field values are rejected.
+ */
+export function parseWorktimeUpdatePayload(value: unknown): WorktimeUpdatePayload | undefined {
+  return normalizeWorktimeUpdatePayload(value);
+}
+
+/** Validate the exact, JSON-shaped payload published on the worktime bus. */
+export function isWorktimeUpdatePayload(value: unknown): value is WorktimeUpdatePayload {
+  return normalizeWorktimeUpdatePayload(value) !== undefined;
+}
+
+/** Alias for callers that prefer validator terminology. */
+export function validateWorktimeUpdatePayload(value: unknown): value is WorktimeUpdatePayload {
+  return isWorktimeUpdatePayload(value);
+}

package/src/index.ts

@@ -0,0 +1,240 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createWorktime, formatDuration, type WorktimeClock } from "./core.js";
+import { parseWorktimeUpdatePayload, WORKTIME_UPDATE_EVENT, type WorktimeUpdatePayload } from "./events.js";
+
+const WORKTIME_STATUS_KEY = "worktime";
+const UPDATE_INTERVAL_MS = 1_000;
+type IntervalHandle = ReturnType<typeof setInterval>;
+type IntervalScheduler = (callback: () => void, delay: number) => IntervalHandle;
+type IntervalCanceller = (handle: IntervalHandle) => void;
+
+export interface WorktimeExtensionOptions {
+  clock?: WorktimeClock;
+  setInterval?: IntervalScheduler;
+  clearInterval?: IntervalCanceller;
+}
+
+function sessionManagerOf(ctx: ExtensionContext): ExtensionContext["sessionManager"] | undefined {
+  try {
+    return ctx.sessionManager;
+  } catch {
+    return undefined;
+  }
+}
+
+function unrefInterval(handle: IntervalHandle): void {
+  if ((typeof handle !== "object" && typeof handle !== "function") || handle === null) return;
+
+  try {
+    const unref = (handle as unknown as { unref?: unknown }).unref;
+    if (typeof unref === "function") unref.call(handle);
+  } catch {
+    // Browser-like or test schedulers may not expose a native unref handle.
+  }
+}
+
+/** Register the worktime lifecycle handlers, with clock/timer seams for tests. */
+export function registerWorktime(pi: ExtensionAPI, options: WorktimeExtensionOptions = {}): void {
+  const worktime = createWorktime(options.clock);
+  const schedule = options.setInterval ?? ((callback, delay) => setInterval(callback, delay));
+  const cancel = options.clearInterval ?? ((handle) => clearInterval(handle));
+
+  let active = false;
+  let sessionGeneration = 0;
+  let activeSessionManager: ExtensionContext["sessionManager"] | undefined;
+  let activeContext: ExtensionContext | undefined;
+  let interval: IntervalHandle | undefined;
+  let intervalToken = 0;
+
+  const ownsSession = (ctx: ExtensionContext): boolean => {
+    if (!active || activeSessionManager === undefined) return false;
+    return sessionManagerOf(ctx) === activeSessionManager;
+  };
+
+  const clearTimer = (): void => {
+    intervalToken += 1;
+    const current = interval;
+    interval = undefined;
+    if (current === undefined) return;
+    try {
+      cancel(current);
+    } catch {
+      // Timer teardown is best effort during host shutdown.
+    }
+  };
+
+  const updateStatus = (ctx: ExtensionContext, payload: WorktimeUpdatePayload): void => {
+    try {
+      if (ctx.mode !== "tui") return;
+      ctx.ui.setStatus(WORKTIME_STATUS_KEY, formatDuration(payload.ms));
+    } catch {
+      // UI teardown can race a lifecycle callback; event publication remains valid.
+    }
+  };
+
+  const clearOwnedStatus = (ctx: ExtensionContext): void => {
+    try {
+      if (ctx.mode !== "tui") return;
+      ctx.ui.setStatus(WORKTIME_STATUS_KEY, undefined);
+    } catch {
+      // UI teardown can race a lifecycle callback; clearing is best-effort.
+    }
+  };
+
+  const deactivateStaleSession = (capturedManager: ExtensionContext["sessionManager"], generation: number): void => {
+    if (!active || generation !== sessionGeneration || activeSessionManager !== capturedManager) return;
+    clearTimer();
+    worktime.end();
+    active = false;
+    activeSessionManager = undefined;
+    activeContext = undefined;
+    // Do not publish or call UI APIs through a context Pi has invalidated.
+  };
+
+  const publish = (ctx: ExtensionContext): void => {
+    if (!ownsSession(ctx)) return;
+
+    const milliseconds = worktime.elapsed();
+    const running = worktime.running;
+    const eventPayload = parseWorktimeUpdatePayload({ ms: milliseconds, running });
+    const statusPayload = parseWorktimeUpdatePayload({ ms: milliseconds, running });
+    if (eventPayload === undefined || statusPayload === undefined) return;
+    const generation = sessionGeneration;
+
+    try {
+      pi.events.emit(WORKTIME_UPDATE_EVENT, eventPayload);
+    } catch {
+      // A third-party event listener must not prevent timer or session cleanup.
+    }
+    if (active && generation === sessionGeneration && ownsSession(ctx)) updateStatus(ctx, statusPayload);
+  };
+
+  const startTimer = (): void => {
+    if (interval !== undefined) return;
+    const generation = sessionGeneration;
+    const capturedContext = activeContext;
+    const capturedManager = activeSessionManager;
+    if (capturedContext === undefined || capturedManager === undefined) return;
+    const token = ++intervalToken;
+    const handle = schedule(() => {
+      if (token !== intervalToken || !active || generation !== sessionGeneration) return;
+      if (sessionManagerOf(capturedContext) !== capturedManager || activeSessionManager !== capturedManager) {
+        deactivateStaleSession(capturedManager, generation);
+        return;
+      }
+      const ctx = activeContext;
+      if (ctx === undefined || !ownsSession(ctx)) {
+        deactivateStaleSession(capturedManager, generation);
+        return;
+      }
+      if (!worktime.running) return;
+      publish(ctx);
+    }, UPDATE_INTERVAL_MS);
+    interval = handle;
+    unrefInterval(handle);
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    const sessionManager = sessionManagerOf(ctx);
+    if (sessionManager === undefined) return;
+    sessionGeneration += 1;
+    clearTimer();
+    worktime.end();
+    worktime.reset();
+    active = true;
+    activeSessionManager = sessionManager;
+    activeContext = ctx;
+    publish(ctx);
+  });
+
+  pi.on("session_tree", (_event, ctx) => {
+    const sessionManager = sessionManagerOf(ctx);
+    if (sessionManager === undefined) return;
+    sessionGeneration += 1;
+    clearTimer();
+    worktime.end();
+    worktime.reset();
+    active = true;
+    activeSessionManager = sessionManager;
+    activeContext = ctx;
+    publish(ctx);
+  });
+
+  pi.on("message_start", (event, ctx) => {
+    if (event.message.role !== "user" || !ownsSession(ctx)) return;
+    activeContext = ctx;
+    worktime.reset();
+    publish(ctx);
+  });
+
+  pi.on("agent_start", (_event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    activeContext = ctx;
+    worktime.start();
+    startTimer();
+    publish(ctx);
+  });
+
+  pi.on("agent_end", (_event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    activeContext = ctx;
+    worktime.end();
+    clearTimer();
+    publish(ctx);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (!ownsSession(ctx)) return;
+    const shutdownGeneration = sessionGeneration + 1;
+    sessionGeneration = shutdownGeneration;
+    clearTimer();
+    worktime.end();
+    publish(ctx);
+    // An event listener can synchronously begin a replacement session. Do not
+    // clear its status or deactivate its state from this old shutdown.
+    if (sessionGeneration !== shutdownGeneration || !active || !ownsSession(ctx)) return;
+    active = false;
+    activeSessionManager = undefined;
+    activeContext = undefined;
+    clearOwnedStatus(ctx);
+  });
+
+  pi.registerCommand("worktime", {
+    description: "Show how long the agent worked on the current prompt",
+    handler: async (_args, ctx) => {
+      let hasUI = false;
+      try {
+        hasUI = ctx.hasUI;
+      } catch {
+        return;
+      }
+      if (!hasUI) return;
+      if (!active || !ownsSession(ctx)) {
+        try {
+          ctx.ui.notify("Worktime unavailable: not initialized for this session.", "warning");
+        } catch {
+          // A stale UI context may already have been disposed.
+        }
+        return;
+      }
+      try {
+        ctx.ui.notify(`Agent worked ${formatDuration(worktime.elapsed())} on this prompt`, "info");
+      } catch {
+        // UI teardown should not turn an informational command into a failure.
+      }
+    },
+  });
+}
+
+export default function worktime(pi: ExtensionAPI): void {
+  registerWorktime(pi);
+}
+
+export { createWorktime, formatDuration, type Worktime, type WorktimeClock } from "./core.js";
+export type { WorktimeUpdatePayload } from "./events.js";
+export {
+  isWorktimeUpdatePayload,
+  parseWorktimeUpdatePayload,
+  validateWorktimeUpdatePayload,
+  WORKTIME_UPDATE_EVENT,
+} from "./events.js";