@senad-d/observme 0.1.0

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@senad-d/observme",
+  "version": "0.1.0",
+  "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",
+  "author": "Senad Dizdarević <112484166+senad-d@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/senad-d/ObservMe.git"
+  },
+  "bugs": {
+    "url": "https://github.com/senad-d/ObservMe/issues"
+  },
+  "homepage": "https://github.com/senad-d/ObservMe#readme",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "cli",
+    "terminal",
+    "typescript",
+    "coding-agent",
+    "observability",
+    "opentelemetry"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    ".env.example",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "docs/**/*.md",
+    "ObservMe-Production-Docs/**/*.md",
+    "dashboards/**/*.json",
+    "dashboards/**/*.yaml",
+    "examples/**/*.yaml",
+    "img/*",
+    "src/**/*.ts",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "dev": "pi --no-extensions -e .",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc --project tsconfig.test.json --noEmit",
+    "lint": "npm run typecheck && npm run typecheck:test && npm run lint:eslint && npm run format:check && npm run check",
+    "lint:eslint": "eslint . --max-warnings=0",
+    "lint:fix": "eslint . --fix",
+    "format:check": "node scripts/check-format.mjs",
+    "test": "node --test test/*.test.mjs test/*.test.ts",
+    "test:integration:collector": "node --test test/integration/collector-debug.test.mjs",
+    "test:integration:grafana-stack": "node --test test/integration/grafana-stack.test.mjs",
+    "test:coverage": "node scripts/test-coverage.mjs",
+    "smoke:discover": "node scripts/smoke-observability.mjs",
+    "smoke:packaged": "node scripts/smoke-packaged-install.mjs",
+    "smoke:handlers": "node scripts/smoke-handler-execution.mjs",
+    "smoke:pi-lifecycle": "node scripts/smoke-pi-lifecycle.mjs",
+    "smoke:pi-runtime": "node scripts/smoke-pi-runtime.mjs",
+    "validate:grafana-obs": "node scripts/validate-grafana-obs-flow.mjs",
+    "check": "node --check scripts/check-package-contents.mjs && node --check scripts/test-coverage.mjs && node --check scripts/smoke-observability.mjs && node --check scripts/smoke-packaged-install.mjs && node --check scripts/smoke-handler-execution.mjs && node --check scripts/smoke-pi-lifecycle.mjs && node --check scripts/smoke-pi-runtime.mjs && node --check scripts/validate-grafana-obs-flow.mjs",
+    "pack:dry-run": "npm pack --dry-run --json",
+    "check:pack": "node scripts/check-package-contents.mjs",
+    "validate": "npm run lint && npm run test && npm run check:pack && npm run smoke:packaged && npm run smoke:handlers && npm run smoke:pi-lifecycle && npm run smoke:pi-runtime"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/senad-d/ObservMe/main/img/demo.gif"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.80.2",
+    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.1",
+    "c8": "^11.0.0",
+    "eslint": "^10.6.0",
+    "globals": "^17.7.0",
+    "typebox": "^1.3.6",
+    "typescript": "6.0.3",
+    "typescript-eslint": "^8.63.0"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/api-logs": "0.220.0",
+    "@opentelemetry/exporter-logs-otlp-proto": "0.220.0",
+    "@opentelemetry/exporter-metrics-otlp-proto": "0.220.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "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/src/commands/obs-agents-runtime.ts

@@ -0,0 +1,150 @@
+import type { AgentLineageContext } from "../pi/agent-lineage.ts";
+import type { AgentChildStatus, AgentTreeNode, AgentTreeSummary, AgentTreeTracker } from "../pi/agent-tree-tracker.ts";
+
+export type ObsAgentWaitJoinKind = "wait" | "join";
+
+export interface ObsAgentWaitJoinHint {
+  readonly kind: ObsAgentWaitJoinKind;
+  readonly id: string;
+  readonly active: boolean;
+  readonly spawnId?: string;
+  readonly childAgentId?: string;
+  readonly childStatus?: AgentChildStatus;
+  readonly joinStatus?: string;
+  readonly reason?: string;
+  readonly durationMs?: number;
+}
+
+export interface StartObsAgentsRuntimeStateOptions {
+  readonly lineage: AgentLineageContext;
+  readonly agentTree?: AgentTreeTracker;
+  readonly sessionId?: string;
+  readonly traceId?: string;
+}
+
+export interface UpdateObsAgentsRuntimeTreeOptions {
+  readonly sessionId?: string;
+  readonly traceId?: string;
+}
+
+export interface ObsAgentsRuntimeSnapshot {
+  readonly lineage?: AgentLineageContext;
+  readonly currentAgent?: AgentTreeNode;
+  readonly summary?: AgentTreeSummary;
+  readonly children: readonly AgentTreeNode[];
+  readonly waitJoinHints: readonly ObsAgentWaitJoinHint[];
+  readonly sessionId?: string;
+  readonly traceId?: string;
+}
+
+interface MutableObsAgentsRuntimeState {
+  lineage?: AgentLineageContext;
+  currentAgent?: AgentTreeNode;
+  summary?: AgentTreeSummary;
+  children: AgentTreeNode[];
+  waitJoinHints: ObsAgentWaitJoinHint[];
+  sessionId?: string;
+  traceId?: string;
+}
+
+const maxWaitJoinHints = 10;
+const runtimeAgentsState: MutableObsAgentsRuntimeState = createEmptyObsAgentsRuntimeState();
+
+export function startObsAgentsRuntimeState(options: StartObsAgentsRuntimeStateOptions): void {
+  replaceObsAgentsRuntimeState(createEmptyObsAgentsRuntimeState());
+  runtimeAgentsState.lineage = options.lineage;
+  runtimeAgentsState.sessionId = normalizeString(options.sessionId);
+  runtimeAgentsState.traceId = normalizeString(options.traceId);
+  if (options.agentTree) updateObsAgentsRuntimeStateFromTree(options.lineage, options.agentTree, options);
+}
+
+export function updateObsAgentsRuntimeStateFromTree(
+  lineage: AgentLineageContext,
+  agentTree: AgentTreeTracker,
+  options: UpdateObsAgentsRuntimeTreeOptions = {},
+): void {
+  runtimeAgentsState.lineage = lineage;
+  runtimeAgentsState.currentAgent = agentTree.getAgent(lineage.agentId);
+  runtimeAgentsState.summary = agentTree.summarize(lineage.rootAgentId);
+  runtimeAgentsState.children = agentTree.getChildren(lineage.agentId);
+  updateOptionalRuntimeString("sessionId", options.sessionId);
+  updateOptionalRuntimeString("traceId", options.traceId);
+}
+
+export function recordObsAgentWaitJoinHint(hint: ObsAgentWaitJoinHint): void {
+  const normalized = normalizeObsAgentWaitJoinHint(hint);
+  if (!normalized) return;
+
+  const existingIndex = runtimeAgentsState.waitJoinHints.findIndex(item => item.kind === normalized.kind && item.id === normalized.id);
+  if (existingIndex >= 0) {
+    runtimeAgentsState.waitJoinHints.splice(existingIndex, 1, normalized);
+  } else {
+    runtimeAgentsState.waitJoinHints.push(normalized);
+  }
+
+  runtimeAgentsState.waitJoinHints = runtimeAgentsState.waitJoinHints.slice(-maxWaitJoinHints);
+}
+
+export function getLocalObsAgentsRuntimeSnapshot(): ObsAgentsRuntimeSnapshot {
+  return {
+    lineage: runtimeAgentsState.lineage,
+    currentAgent: runtimeAgentsState.currentAgent,
+    summary: runtimeAgentsState.summary,
+    children: [...runtimeAgentsState.children],
+    waitJoinHints: [...runtimeAgentsState.waitJoinHints],
+    sessionId: runtimeAgentsState.sessionId,
+    traceId: runtimeAgentsState.traceId,
+  };
+}
+
+export function clearObsAgentsRuntimeState(): void {
+  replaceObsAgentsRuntimeState(createEmptyObsAgentsRuntimeState());
+}
+
+function normalizeObsAgentWaitJoinHint(hint: ObsAgentWaitJoinHint): ObsAgentWaitJoinHint | undefined {
+  const id = normalizeString(hint.id);
+  if (!id) return undefined;
+
+  return {
+    kind: hint.kind,
+    id,
+    active: hint.active,
+    spawnId: normalizeString(hint.spawnId),
+    childAgentId: normalizeString(hint.childAgentId),
+    childStatus: hint.childStatus,
+    joinStatus: normalizeString(hint.joinStatus),
+    reason: normalizeString(hint.reason),
+    durationMs: normalizeDurationMs(hint.durationMs),
+  };
+}
+
+function normalizeDurationMs(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value) || value < 0) return undefined;
+  return Math.trunc(value);
+}
+
+function updateOptionalRuntimeString(key: "sessionId" | "traceId", value: string | undefined): void {
+  if (value !== undefined) runtimeAgentsState[key] = normalizeString(value);
+}
+
+function replaceObsAgentsRuntimeState(state: MutableObsAgentsRuntimeState): void {
+  runtimeAgentsState.lineage = state.lineage;
+  runtimeAgentsState.currentAgent = state.currentAgent;
+  runtimeAgentsState.summary = state.summary;
+  runtimeAgentsState.children = state.children;
+  runtimeAgentsState.waitJoinHints = state.waitJoinHints;
+  runtimeAgentsState.sessionId = state.sessionId;
+  runtimeAgentsState.traceId = state.traceId;
+}
+
+function createEmptyObsAgentsRuntimeState(): MutableObsAgentsRuntimeState {
+  return {
+    children: [],
+    waitJoinHints: [],
+  };
+}
+
+function normalizeString(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed || undefined;
+}