@senad-d/observme 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -21,8 +21,9 @@
 
 ### Changed
 
+- Raised the release-tested Pi and exact compatibility CI target to 0.81.1 while retaining 0.80.5 as the earliest validated target.
 - Made the 0.1.5 hardening patch self-contained with explicit review units, all imported production modules included, and unrelated specification history preserved.
-- Established a typed Pi event registration contract, removed non-event legacy registrations, pinned the release-resolved Pi API, and added minimum/release compatibility validation with pre-registration diagnostics.
+- Established a typed Pi event registration contract, removed non-event legacy registrations, pinned the release-tested Pi API for validation, and added capability-based pre-registration diagnostics.
 - Centralized embedded-credential Grafana URL diagnostics so configuration validation, readiness checks, URL construction, and transports share one safe failure class and operator guidance.
 - Documented credential-free Grafana base URLs and the fail-closed canonical project-file boundary across configuration, security, query, and troubleshooting guidance.
 - Completed production active-agent lease documentation, raw-query migration guidance, GitHub Actions/self-hosted clock and cleanup runbooks, missing/expired-lease troubleshooting, Collector restart semantics, and sanitized release-validation evidence.
@@ -42,9 +43,8 @@
 
 ### Fixed
 
-- Simplified Pi SemVer validation into focused numeric-core and metadata checks, and made missing project-path component reversal explicit.
-- Accepted supported stable Pi versions with SemVer build metadata while preserving bounded diagnostics and prerelease rejection.
-- Rejected prerelease Pi builds excluded by the declared stable compatibility range before extension registration.
+- Removed Pi version gating from extension startup entirely; tested versions are evidence only, essential ExtensionAPI capabilities are checked before registration, and optional APIs remain feature-detected.
+- Made missing project-path component reversal explicit.
 - Applied one control-safe 64-row/8,192-character policy to every `/obs` notification and capped query result counts at configuration and runtime boundaries.
 - Coupled canonical project config, `.env`, and starter-config I/O to identity-verified file handles so concurrent symlink and ancestor swaps fail closed without exposing external paths.
 - Rejected credentials embedded in Grafana base URLs during config validation, query readiness, and transport preflight without exposing their values.

package/docs/compatibility-matrix.md

@@ -1,14 +1,14 @@
 # ObservMe Compatibility Matrix
 
-Last updated: 2026-07-14
+Last updated: 2026-07-22
 
 This matrix records the ObservMe runtime and observability-stack versions exercised or pinned for the current release line. A component is marked **validated** only when the named command actually exercised it; configured CI targets remain distinct from completed local or workflow evidence.
 
 ## Pi version policy
 
-ObservMe 0.1.x supports `@earendil-works/pi-coding-agent` `>=0.80.5 <0.81.0`. The Pi-mandated core package peers remain in `peerDependencies` with `"*"`, while release development dependencies are pinned exactly to 0.80.6 and CI installs both the 0.80.5 minimum and the 0.80.6 release-resolved target explicitly. Extension startup checks Pi's exported `VERSION` and required APIs before registering any handler or command.
+ObservMe never uses Pi's reported version as a startup gate. The Pi-mandated core package peers remain in `peerDependencies` with `"*"`, while exact 0.80.5 and 0.81.1 targets record compatibility evidence in CI. Before registering anything, startup checks only the essential `ExtensionAPI` capabilities `on` and `registerCommand`. When those methods exist, ObservMe starts regardless of whether Pi's version is older, newer, prerelease, malformed, or unavailable. Optional APIs are feature-detected by the handlers that use them.
 
-The 0.80.5 minimum is evidence-based: its exported extension contract includes `session_info_changed`, which ObservMe requires for live rename metadata; 0.80.2 does not. Pi's current extension overloads do not include `bashExecution`, `model_change`, or `thinking_level_change`. `bashExecution` is an `AgentMessage` role observed through `message_end`, while model and thinking changes are session entry types represented at runtime by `model_select` and `thinking_level_select`; ObservMe no longer registers those three non-event names.
+Pi 0.80.5 is the earliest tested version, not a runtime minimum: its exported extension contract includes `session_info_changed`, which ObservMe uses for live rename metadata. Pi's current extension overloads do not include `bashExecution`, `model_change`, or `thinking_level_change`. `bashExecution` is an `AgentMessage` role observed through `message_end`, while model and thinking changes are session entry types represented at runtime by `model_select` and `thinking_level_select`; ObservMe no longer registers those three non-event names. Tested versions provide release evidence only and never define an accepted or rejected runtime range.
 
 ## Validation record
 
@@ -18,9 +18,11 @@ The 0.80.5 minimum is evidence-based: its exported extension contract includes `
 | 2026-07-07 | Local Docker 29.5.2 with Collector Contrib 0.104.0 | `npm run test:integration:collector` | Starts a local debug-exporter Collector container, exports representative ObservMe traces/metrics/logs, and asserts default-disabled content capture is absent. |
 | 2026-07-07 | Local Docker 29.5.2 with the pinned Grafana stack | `npm run test:integration:grafana-stack` | Starts `observability-stack/` services, exports representative ObservMe telemetry, queries Tempo by trace ID and lineage attributes, queries Loki by session ID, queries Prometheus token totals, and validates Grafana dashboard provisioning imports. |
 | Continuous integration target | GitHub Actions `ubuntu-latest`, Node.js 22.19.0 | `npm ci --ignore-scripts` then `npm run validate` | CI target from `.github/workflows/ci.yml`; record the workflow run URL here after each release validation. |
-| Pi compatibility CI matrix (configured 2026-07-14) | GitHub Actions `ubuntu-latest`, Node.js 22.19.0; exact Pi 0.80.5 and 0.80.6 matrix targets | Exact Pi install, version assertion, then `npm run validate:pi-compatibility` | Compile-time event fixtures, compatibility diagnostics, package install, handler/lifecycle smoke, and a real Pi RPC runtime are exercised separately at the declared minimum and release-resolved versions. |
-| 2026-07-14 | Local Node.js v26.0.0, npm 11.12.1; exact `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` 0.80.5 | Exact version assertion then `npm run validate:pi-compatibility` | Passed typecheck, typed event contracts, compatibility diagnostics, packaged install, handler/lifecycle smoke, and real Pi RPC runtime at the declared minimum. |
-| 2026-07-14 | Local Node.js v26.0.0, npm 11.12.1; exact `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` 0.80.6 | Exact version assertion then `npm run validate:pi-compatibility` | Passed the same compatibility suite at the release-resolved version. |
+| Pi compatibility CI matrix (updated 2026-07-22) | GitHub Actions `ubuntu-latest`, Node.js 22.19.0; exact Pi 0.80.5 and 0.81.1 matrix targets | Exact Pi install, version assertion, then `npm run validate:pi-compatibility` | Compile-time event fixtures, capability diagnostics, package install, handler/lifecycle smoke, and a real Pi RPC runtime are exercised separately at the earliest-tested and release-tested versions. |
+| 2026-07-14 | Local Node.js v26.0.0, npm 11.12.1; exact `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` 0.80.5 | Exact version assertion then `npm run validate:pi-compatibility` | Passed typecheck, typed event contracts, capability diagnostics, packaged install, handler/lifecycle smoke, and real Pi RPC runtime at the earliest-tested version. |
+| 2026-07-14 | Local Node.js v26.0.0, npm 11.12.1; exact `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` 0.80.6 | Exact version assertion then `npm run validate:pi-compatibility` | Passed the same compatibility suite at the former release-tested version. |
+| 2026-07-22 | Local Node.js v26.0.0, npm 11.12.1; exact `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` 0.81.1 | Exact version assertion, typechecks, compatibility tests, packaged install, handler/lifecycle smoke, and real Pi RPC runtime | Passed the complete `npm run validate:pi-compatibility` suite at the current release-tested version. |
+| 2026-07-22 | Local Node.js v26.0.0, npm 11.12.1; exact Pi 0.81.1 development dependencies | `npm run validate` | Passed source/test typechecks, ESLint, formatting, 618 unit/contract tests, package-content checks, packaged-install smoke, handler smoke, Pi lifecycle smoke, and real Pi runtime smoke. |
 | Lease cancellation CI profile (configured 2026-07-14) | GitHub-hosted Linux `ubuntu-latest` (exact `ImageOS`/`ImageVersion` recorded in the Actions runner log); Node.js 22.19.0; Collector Contrib 0.104.0; Prometheus 2.53.1; Grafana 11.1.0 | `npm run test:active-agent-lease:contracts` then `npm run test:integration:active-agent-lease` | The bounded `lease-cancellation` job validates clean shutdown, `SIGTERM`, and cancellation-oriented `SIGKILL` convergence against the pinned Collector and Prometheus without secrets or a Grafana dependency. Grafana 11.1.0 is the recorded dashboard compatibility baseline validated separately by `npm run test:integration:grafana-stack`. `if: always()` cleanup is best effort; lease expiry is the asserted correctness mechanism. |
 | 2026-07-14 | Local Node.js v26.0.0, npm 11.12.1 | `npm run validate` | Passed 493 unit/contract tests plus typecheck, ESLint, formatting, script, package-content, packaged-install, handler, Pi lifecycle, and Pi runtime checks for the lease release candidate. |
 | 2026-07-14 | Local Docker 29.5.2, Compose 5.1.4, Collector Contrib 0.104.0 | `npm run test:integration:collector`; Compose config; pinned Collector `validate` | Passed representative OTLP export, Compose interpolation, and the shipped Collector config validation. |
@@ -34,7 +36,7 @@ Active-agent lease interpretation additionally requires producer and Prometheus
 
 | Component | Version tested or pinned | Source of truth | Status | Evidence and notes |
 | --- | --- | --- | --- | --- |
-| Pi package API | Supported: `@earendil-works/pi-coding-agent` >=0.80.5 <0.81.0; release-resolved `@earendil-works/pi-coding-agent` 0.80.6 and `@earendil-works/pi-ai` 0.80.6 | `package.json` `observmeCompatibility`, exact dev dependencies, `package-lock.json`, `.github/workflows/ci.yml` | Validated locally at minimum and release-resolved versions; exact CI matrix configured | `npm run validate:pi-compatibility` typechecks exported event contracts, tests pre-registration diagnostics, installs the package, runs handler/lifecycle smoke, and launches the real Pi RPC runtime. |
+| Pi package API | Runtime policy: required API capabilities only; version never gates startup. Earliest tested Pi: 0.80.5; release-tested `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai`: 0.81.1 | `package.json` `observmeCompatibility`, exact dev dependencies, `package-lock.json`, `.github/workflows/ci.yml` | Validated locally at earliest-tested 0.80.5 and release-tested 0.81.1; exact CI matrix configured | `npm run validate:pi-compatibility` typechecks exported event contracts, tests pre-registration capability diagnostics, installs the package, runs handler/lifecycle smoke, and launches the real Pi RPC runtime. Pi version values do not participate in startup acceptance. |
 | Node.js | Local: 26.0.0; CI target/minimum: 22.19.0 | `node --version`, `package.json` `engines.node`, `.github/workflows/ci.yml` | Validated locally for 26.0.0; CI target pinned at 22.19.0 | Local validation ran on 26.0.0. CI is configured to validate on 22.19.0, which is also the minimum supported Node.js version. |
 | OpenTelemetry JS package set | `@opentelemetry/api` 1.9.1; `@opentelemetry/api-logs` 0.220.0; OTLP proto exporters 0.220.0; `@opentelemetry/resources` 2.9.0; `@opentelemetry/sdk-logs` 0.220.0; `@opentelemetry/sdk-metrics` 2.9.0; `@opentelemetry/sdk-trace-base` 2.9.0; `@opentelemetry/sdk-trace-node` 2.9.0 | `package.json`, `package-lock.json` | Validated locally | `npm run validate` includes the OTEL lifecycle/exporter unit tests under `test/otel-*.test.mjs`. |
 

package/docs/review-validation.md

@@ -93,6 +93,16 @@ This sanitized record covers the production active-agent lease release candidate
 
 Post-run cleanup check found no containers or networks labeled for the active-agent lease integration and no `observme-grafana-it-*` containers or networks. Release remains blocked on the unrelated broad Grafana-stack validation unless the release owner accepts the explicitly allowed pre-existing blocker; all lease-specific release criteria passed.
 
+## Pi 0.81.1 compatibility validation — 2026-07-22
+
+This sanitized record covers the compatibility-policy correction against exact `@earendil-works/pi-coding-agent` and `@earendil-works/pi-ai` 0.81.1 development dependencies on local Node.js v26.0.0 and npm 11.12.1. No project, model, Grafana, or registry credentials were required or printed.
+
+| Command | Result | Evidence and notes |
+| --- | --- | --- |
+| `npm run validate:pi-compatibility` | Pass | Source/test typechecks, compatibility and event-mapping tests, packaged-install smoke, handler and lifecycle smoke, and the real Pi RPC runtime passed against Pi 0.81.1. |
+| `npm run validate` | Pass | ESLint, formatting, script checks, 618 unit/contract tests, package-content validation, packaged-install smoke, handler smoke, Pi lifecycle smoke, and real Pi runtime smoke passed. |
+| `npm audit --omit=dev` | Pass | The production dependency tree reported no vulnerabilities. |
+
 ## Review-closure evidence categories
 
 - **Read-only/check-only** — commands that inspect, type-check, lint, audit, run tests, dry-run packaging, or smoke local deterministic fixtures without publishing or writing tracked files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/observme",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "description": "ObservMe: a Pi extension that instruments Pi agent sessions and exports OpenTelemetry traces, metrics, and logs to an external observability stack (OTel Collector, Grafana Tempo/Loki/Prometheus).",
   "license": "MIT",
@@ -76,9 +76,9 @@
   },
   "observmeCompatibility": {
     "pi": {
-      "minimumVersion": "0.80.5",
-      "releaseTestedVersion": "0.80.6",
-      "supportedRange": ">=0.80.5 <0.81.0"
+      "earliestTestedVersion": "0.80.5",
+      "releaseTestedVersion": "0.81.1",
+      "runtimePolicy": "required-api-capabilities"
     }
   },
   "pi": {
@@ -96,8 +96,8 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.80.6",
-    "@earendil-works/pi-coding-agent": "0.80.6",
+    "@earendil-works/pi-ai": "0.81.1",
+    "@earendil-works/pi-coding-agent": "0.81.1",
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.1.1",
     "c8": "^11.0.0",

package/src/extension.ts

@@ -1,12 +1,12 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerObsCommand } from "./commands/obs.ts";
-import { assertObservMePiCompatibility } from "./pi/compatibility.ts";
+import { assertObservMePiCapabilities } from "./pi/compatibility.ts";
 import { registerHandlers } from "./pi/handlers.ts";
 const partialInitializationErrorMessage =
   "ObservMe extension initialization failed while registering /obs after Pi event handlers were already registered. Pi ExtensionAPI does not expose unregister hooks for event handlers or slash commands, so ObservMe cannot roll back partial registration; restart Pi after fixing command registration.";
 
 export default function observme(pi: ExtensionAPI): void {
-  assertObservMePiCompatibility(pi);
+  assertObservMePiCapabilities(pi);
   // Only the Pi process environment is eligible for launcher-provided lineage.
   // Session config loading keeps trusted project .env values out of this boundary.
   registerHandlers(pi, { trustedParentContext: true });

package/src/pi/compatibility.ts

@@ -1,34 +1,17 @@
-import { VERSION as PI_VERSION } from "@earendil-works/pi-coding-agent";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export const EARLIEST_TESTED_PI_VERSION = "0.80.5";
+export const RELEASE_TESTED_PI_VERSION = "0.81.1";
+export const PI_RUNTIME_COMPATIBILITY_POLICY = "required-api-capabilities" as const;
 
-export const MINIMUM_SUPPORTED_PI_VERSION = "0.80.5";
-export const RELEASE_TESTED_PI_VERSION = "0.80.6";
-const FIRST_UNSUPPORTED_PI_VERSION = "0.81.0";
-export const SUPPORTED_PI_VERSION_RANGE =
-  `>=${MINIMUM_SUPPORTED_PI_VERSION} <${FIRST_UNSUPPORTED_PI_VERSION}`;
+const capabilityErrorPrefix = "ObservMe/Pi API capability error";
+const requiredPiMethods = ["on", "registerCommand"] as const;
 
-const compatibilityErrorPrefix = "ObservMe/Pi API compatibility error";
-const MAX_DETECTED_PI_VERSION_LENGTH = 128;
-const piVersionCorePattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
-const semanticVersionIdentifierPattern = /^[0-9A-Za-z-]+$/u;
-const numericIdentifierPattern = /^\d+$/u;
-const requiredPiMethods = ["on", "registerCommand", "appendEntry", "getThinkingLevel"] as const;
-
-export function assertObservMePiCompatibility(
-  pi: unknown,
-  piVersion = PI_VERSION,
-): asserts pi is ExtensionAPI {
+/** Pi's reported version is intentionally not part of this startup decision. */
+export function assertObservMePiCapabilities(pi: unknown): void {
   const missingMethods = findMissingPiMethods(pi);
-  const detectedVersion = normalizeDetectedVersion(piVersion);
-  const versionSupported = isSupportedPiVersion(detectedVersion);
-  if (versionSupported && missingMethods.length === 0) return;
-
-  const reasons: string[] = [];
-  if (!versionSupported) reasons.push(`detected Pi ${detectedVersion}`);
-  if (missingMethods.length > 0) reasons.push(`missing required API method(s): ${missingMethods.join(", ")}`);
+  if (missingMethods.length === 0) return;
 
   throw new TypeError(
-    `${compatibilityErrorPrefix}: ObservMe requires @earendil-works/pi-coding-agent ${SUPPORTED_PI_VERSION_RANGE}; ${reasons.join("; ")}. No ObservMe event handlers or commands were registered.`,
+    `${capabilityErrorPrefix}: ObservMe requires ExtensionAPI method(s): ${missingMethods.join(", ")}. Pi version is not used as a startup gate. No ObservMe event handlers or commands were registered.`,
   );
 }
 
@@ -45,77 +28,3 @@ function findMissingPiMethods(pi: unknown): string[] {
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
-
-function normalizeDetectedVersion(value: unknown): string {
-  if (typeof value !== "string") return "unknown";
-  const trimmed = value.trim();
-  if (trimmed.length === 0 || trimmed.length > MAX_DETECTED_PI_VERSION_LENGTH) return "unknown";
-  return parsePiVersion(trimmed) ? trimmed : "unknown";
-}
-
-function isSupportedPiVersion(version: string): boolean {
-  const detected = parsePiVersion(version);
-  const minimum = parsePiVersion(MINIMUM_SUPPORTED_PI_VERSION);
-  const maximum = parsePiVersion(FIRST_UNSUPPORTED_PI_VERSION);
-  if (!detected || detected.prerelease || !minimum || !maximum) return false;
-
-  return comparePiVersions(detected, minimum) >= 0 && comparePiVersions(detected, maximum) < 0;
-}
-
-interface PiVersion {
-  major: number;
-  minor: number;
-  patch: number;
-  prerelease?: string;
-}
-
-function parsePiVersion(version: string): PiVersion | undefined {
-  const buildSeparatorIndex = version.indexOf("+");
-  const versionAndPrerelease = buildSeparatorIndex === -1 ? version : version.slice(0, buildSeparatorIndex);
-  const build = buildSeparatorIndex === -1 ? undefined : version.slice(buildSeparatorIndex + 1);
-  if (build !== undefined && !hasValidSemanticVersionIdentifiers(build, true)) return undefined;
-
-  const prereleaseSeparatorIndex = versionAndPrerelease.indexOf("-");
-  const coreVersion = prereleaseSeparatorIndex === -1
-    ? versionAndPrerelease
-    : versionAndPrerelease.slice(0, prereleaseSeparatorIndex);
-  const prerelease = prereleaseSeparatorIndex === -1
-    ? undefined
-    : versionAndPrerelease.slice(prereleaseSeparatorIndex + 1);
-  if (prerelease !== undefined && !hasValidSemanticVersionIdentifiers(prerelease, false)) return undefined;
-
-  const match = piVersionCorePattern.exec(coreVersion);
-  if (!match) return undefined;
-
-  const major = Number(match[1]);
-  const minor = Number(match[2]);
-  const patch = Number(match[3]);
-  if (!Number.isSafeInteger(major) || !Number.isSafeInteger(minor) || !Number.isSafeInteger(patch)) {
-    return undefined;
-  }
-
-  return {
-    major,
-    minor,
-    patch,
-    ...(prerelease === undefined ? {} : { prerelease }),
-  };
-}
-
-function hasValidSemanticVersionIdentifiers(value: string, allowLeadingZeros: boolean): boolean {
-  for (const identifier of value.split(".")) {
-    if (!semanticVersionIdentifierPattern.test(identifier)) return false;
-    if (!allowLeadingZeros && hasInvalidNumericIdentifier(identifier)) return false;
-  }
-  return true;
-}
-
-function hasInvalidNumericIdentifier(identifier: string): boolean {
-  return identifier.length > 1 && identifier.startsWith("0") && numericIdentifierPattern.test(identifier);
-}
-
-function comparePiVersions(left: PiVersion, right: PiVersion): number {
-  if (left.major !== right.major) return left.major - right.major;
-  if (left.minor !== right.minor) return left.minor - right.minor;
-  return left.patch - right.patch;
-}

package/src/pi/handler-runtime.ts

@@ -65,8 +65,8 @@ import type { AgentWaitJoinState, SubagentSpawnState } from "./subagent-types.ts
 
 export const OBSERVME_SEMCONV_VERSION = "0.1.0";
 
-const piApiCompatibilityErrorMessage =
-  "ObservMe/Pi API compatibility error: expected Pi ExtensionAPI with on(eventName, handler) before registering ObservMe handlers.";
+const piApiCapabilityErrorMessage =
+  "ObservMe/Pi API capability error: expected Pi ExtensionAPI with on(eventName, handler) before registering ObservMe handlers.";
 const eventRegistrationOrder = [
   "session_start",
   "session_info_changed",
@@ -143,10 +143,10 @@ export class SerializedLifecycleQueue {
 }
 
 export function resolveObservMePiApi(pi: unknown): ObservMePiApi {
-  if (!isRecord(pi)) throw new TypeError(piApiCompatibilityErrorMessage);
+  if (!isRecord(pi)) throw new TypeError(piApiCapabilityErrorMessage);
 
   const on = pi.on;
-  if (typeof on !== "function") throw new TypeError(piApiCompatibilityErrorMessage);
+  if (typeof on !== "function") throw new TypeError(piApiCapabilityErrorMessage);
 
   const appendEntry = typeof pi.appendEntry === "function"
     ? (pi.appendEntry.bind(pi) as NonNullable<ObservMePiApi["appendEntry"]>)