@senad-d/observme 0.1.1 → 0.1.2

package/examples/integrations/subagent-runner.ts

@@ -0,0 +1,262 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  requestObservMeIntegration,
+  type ObservMeChildStatus,
+  type ObservMeIntegrationApi,
+  type ObservMeJoinStatus,
+  type ObservMeProcessEnvironment,
+  type ObservMeSpawnReason,
+  type ObservMeSpawnType,
+  type ObservMeStartedSubagent,
+} from "@senad-d/observme/integration";
+
+/**
+ * Transport-neutral context supplied to a child launcher.
+ *
+ * Implement ChildTransport with child_process, Pi RPC, tmux, SSH, a container,
+ * a queue, or another process manager. Always pass environment unchanged to
+ * the child Pi process and never log it.
+ */
+export interface ChildLaunchContext {
+  readonly environment: ObservMeProcessEnvironment;
+  readonly spawnId?: string;
+  readonly childAgentId?: string;
+  readonly traceContextPropagated: boolean;
+}
+
+export interface ChildRunResult<Value> {
+  readonly status: "completed" | "failed" | "cancelled" | "timeout";
+  readonly value?: Value;
+  readonly failurePropagated?: boolean;
+}
+
+export interface ChildTransport<Request, Handle, Value> {
+  launch(request: Request, context: ChildLaunchContext, signal?: AbortSignal): Promise<Handle>;
+  wait(handle: Handle, signal?: AbortSignal): Promise<ChildRunResult<Value>>;
+}
+
+export interface ObservableSubagentRunOptions<Request> {
+  readonly request: Request;
+  readonly command?: string;
+  readonly args?: readonly string[];
+  readonly spawnType?: ObservMeSpawnType;
+  readonly spawnReason?: ObservMeSpawnReason;
+  readonly toolCallId?: string;
+  readonly environment?: ObservMeProcessEnvironment;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Generic adapter that adds ObservMe lifecycle reporting to any child transport.
+ *
+ * The transport owns process control and result delivery. ObservMe owns only
+ * spawn/wait/join telemetry and propagation context. When ObservMe is absent or
+ * inactive, the transport still runs with the supplied base environment.
+ */
+export class ObservableSubagentRunner<Request, Handle, Value> {
+  readonly #pi: ExtensionAPI;
+  readonly #transport: ChildTransport<Request, Handle, Value>;
+
+  constructor(pi: ExtensionAPI, transport: ChildTransport<Request, Handle, Value>) {
+    this.#pi = pi;
+    this.#transport = transport;
+  }
+
+  async run(options: ObservableSubagentRunOptions<Request>): Promise<ChildRunResult<Value>> {
+    const observme = requestObservMeIntegration(this.#pi);
+    const started = startObservMeSubagent(observme, options);
+    const context = createLaunchContext(started, options.environment);
+    let handle: Handle;
+
+    try {
+      handle = await this.#transport.launch(options.request, context, options.signal);
+      completeObservMeLaunch(observme, started);
+    } catch (error) {
+      failObservMeLaunch(observme, started, error);
+      throw error;
+    }
+
+    return this.waitForResult(observme, started, handle, options.signal);
+  }
+
+  private async waitForResult(
+    observme: ObservMeIntegrationApi | undefined,
+    started: ObservMeStartedSubagent | undefined,
+    handle: Handle,
+    signal: AbortSignal | undefined,
+  ): Promise<ChildRunResult<Value>> {
+    const wait = startObservMeWait(observme, started);
+
+    try {
+      const result = await this.#transport.wait(handle, signal);
+      endObservMeWait(observme, started, wait, result);
+      recordObservMeJoin(observme, started, result);
+      return result;
+    } catch (error) {
+      endObservMeWaitFailure(observme, started, wait);
+      recordObservMeJoinFailure(observme, started);
+      throw error;
+    }
+  }
+}
+
+function startObservMeSubagent<Request>(
+  observme: ObservMeIntegrationApi | undefined,
+  options: ObservableSubagentRunOptions<Request>,
+): ObservMeStartedSubagent | undefined {
+  const result = observme?.startSubagent({
+    command: options.command,
+    args: options.args,
+    spawnType: options.spawnType ?? "extension",
+    spawnReason: options.spawnReason ?? "delegated_task",
+    toolCallId: options.toolCallId,
+    env: options.environment ?? process.env,
+  });
+  return result?.ok ? result : undefined;
+}
+
+function createLaunchContext(
+  started: ObservMeStartedSubagent | undefined,
+  environment: ObservMeProcessEnvironment | undefined,
+): ChildLaunchContext {
+  return {
+    environment: started?.env ?? environment ?? process.env,
+    spawnId: started?.spawnId,
+    childAgentId: started?.childAgentId,
+    traceContextPropagated: started?.traceContextPropagated ?? false,
+  };
+}
+
+function completeObservMeLaunch(
+  observme: ObservMeIntegrationApi | undefined,
+  started: ObservMeStartedSubagent | undefined,
+): void {
+  if (!observme || !started) return;
+  observme.completeSubagent(started.spawnId, {
+    childAgentId: started.childAgentId,
+    childStatus: "active",
+  });
+}
+
+function failObservMeLaunch(
+  observme: ObservMeIntegrationApi | undefined,
+  started: ObservMeStartedSubagent | undefined,
+  error: unknown,
+): void {
+  if (!observme || !started) return;
+  observme.failSubagent(started.spawnId, {
+    childAgentId: started.childAgentId,
+    errorClass: safeErrorClass(error),
+  });
+}
+
+function startObservMeWait(
+  observme: ObservMeIntegrationApi | undefined,
+  started: ObservMeStartedSubagent | undefined,
+) {
+  if (!observme || !started) return undefined;
+  const wait = observme.startWait({
+    spawnId: started.spawnId,
+    childAgentId: started.childAgentId,
+    childStatus: "active",
+    reason: "child_running",
+  });
+  return wait.ok ? wait : undefined;
+}
+
+function endObservMeWait<Value>(
+  observme: ObservMeIntegrationApi | undefined,
+  started: ObservMeStartedSubagent | undefined,
+  wait: { readonly id: string } | undefined,
+  result: ChildRunResult<Value>,
+): void {
+  if (!observme || !started || !wait) return;
+  observme.endWait(wait.id, {
+    spawnId: started.spawnId,
+    childAgentId: started.childAgentId,
+    childStatus: childStatus(result.status),
+    joinStatus: joinStatus(result.status),
+    reason: "child_running",
+  });
+}
+
+function endObservMeWaitFailure(
+  observme: ObservMeIntegrationApi | undefined,
+  started: ObservMeStartedSubagent | undefined,
+  wait: { readonly id: string } | undefined,
+): void {
+  if (!observme || !started || !wait) return;
+  observme.endWait(wait.id, {
+    spawnId: started.spawnId,
+    childAgentId: started.childAgentId,
+    childStatus: "failed",
+    joinStatus: "failed",
+    reason: "child_running",
+    failurePropagated: true,
+  });
+}
+
+function recordObservMeJoin<Value>(
+  observme: ObservMeIntegrationApi | undefined,
+  started: ObservMeStartedSubagent | undefined,
+  result: ChildRunResult<Value>,
+): void {
+  if (!observme || !started) return;
+  const status = joinStatus(result.status);
+  const child = childStatus(result.status);
+  const join = observme.startJoin({
+    spawnId: started.spawnId,
+    childAgentId: started.childAgentId,
+    childStatus: child,
+    joinStatus: status,
+    reason: "dependency",
+  });
+  if (!join.ok) return;
+  observme.endJoin(join.id, {
+    spawnId: started.spawnId,
+    childAgentId: started.childAgentId,
+    childStatus: child,
+    joinStatus: status,
+    reason: "dependency",
+    failurePropagated: result.failurePropagated ?? result.status === "failed",
+  });
+}
+
+function recordObservMeJoinFailure(
+  observme: ObservMeIntegrationApi | undefined,
+  started: ObservMeStartedSubagent | undefined,
+): void {
+  if (!observme || !started) return;
+  const join = observme.startJoin({
+    spawnId: started.spawnId,
+    childAgentId: started.childAgentId,
+    childStatus: "failed",
+    joinStatus: "failed",
+    reason: "dependency",
+  });
+  if (!join.ok) return;
+  observme.endJoin(join.id, {
+    spawnId: started.spawnId,
+    childAgentId: started.childAgentId,
+    childStatus: "failed",
+    joinStatus: "failed",
+    reason: "dependency",
+    failurePropagated: true,
+  });
+}
+
+function childStatus(status: ChildRunResult<unknown>["status"]): ObservMeChildStatus {
+  if (status === "completed") return "completed";
+  if (status === "cancelled") return "cancelled";
+  return "failed";
+}
+
+function joinStatus(status: ChildRunResult<unknown>["status"]): ObservMeJoinStatus {
+  return status;
+}
+
+function safeErrorClass(error: unknown): string {
+  if (!(error instanceof Error)) return "launcher_error";
+  const normalized = error.name.trim().toLowerCase().replaceAll(/[^a-z0-9_.:-]/gu, "_");
+  return /^[a-z][a-z0-9_.:-]{0,63}$/u.test(normalized) ? normalized : "launcher_error";
+}

package/examples/observme.yaml

@@ -1,3 +1,7 @@
+# Privacy-preserving local-development profile for the supported ObservMe stack.
+# Copy to <project>/<CONFIG_DIR_NAME>/observme.yaml (normally .pi/observme.yaml).
+# Keep credentials in environment variables or a trusted project .env, not here.
+# Guide: examples/README.md; full schema: docs/reference/12-configuration-reference.md.
 observme:
   enabled: true
   environment: development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/observme",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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",
@@ -9,6 +9,10 @@
     "type": "git",
     "url": "git+https://github.com/senad-d/ObservMe.git"
   },
+  "exports": {
+    ".": "./src/extension.ts",
+    "./integration": "./src/integration.ts"
+  },
   "bugs": {
     "url": "https://github.com/senad-d/ObservMe/issues"
   },
@@ -34,9 +38,11 @@
     "SECURITY.md",
     "CHANGELOG.md",
     "docs/**/*.md",
-    "ObservMe-Production-Docs/**/*.md",
+    "skills/**/*.md",
     "dashboards/**/*.json",
     "dashboards/**/*.yaml",
+    "examples/**/*.md",
+    "examples/**/*.ts",
     "examples/**/*.yaml",
     "img/*",
     "src/**/*.ts",
@@ -69,6 +75,9 @@
     "extensions": [
       "./src/extension.ts"
     ],
+    "skills": [
+      "./skills"
+    ],
     "image": "https://raw.githubusercontent.com/senad-d/ObservMe/main/img/demo.gif"
   },
   "peerDependencies": {

package/skills/observme-docs/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: observme-docs
+description: Answers questions about the ObservMe Pi extension, including installation, /obs commands, configuration, privacy and content capture, OpenTelemetry export, Grafana dashboards, metrics, traces, logs, troubleshooting, compatibility, development, and parent/subagent lineage. Use whenever a user asks how ObservMe works, how to set it up or operate it, or where its behavior is documented.
+---
+
+# ObservMe documentation
+
+Use the packaged ObservMe documentation to answer questions accurately and point users to the most relevant file and section. Do not modify files unless the user separately asks for changes.
+
+## Resolve packaged documentation paths
+
+This skill and its documentation ship in the same installed Pi package. Do not resolve documentation paths against the current working directory or assume that an ObservMe repository checkout exists.
+
+1. Use the absolute path from which Pi loaded this `SKILL.md` as `SKILL_FILE`.
+2. Set `SKILL_DIR` to the directory containing `SKILL_FILE`.
+3. Set `PACKAGE_ROOT` to the absolute path obtained by resolving `../..` from `SKILL_DIR`.
+4. Treat every `package:<path>` entry below as a path relative to `PACKAGE_ROOT`. Pass the resulting absolute filesystem path to the read tool.
+
+For example, `package:docs/configuration.md` means the absolute equivalent of `<PACKAGE_ROOT>/docs/configuration.md`, regardless of where npm, git, or a local Pi package was installed. Never pass the literal `package:` prefix to a file tool.
+
+Start with `package:docs/README.md` only when the request is broad or its topic is unclear. For a specific request, read the primary document from the routing table directly. Do not load the entire documentation set. If a routed file is absent from `PACKAGE_ROOT`, report that the installed ObservMe package is incomplete instead of silently reading a similarly named file from the current project.
+
+## Route questions
+
+| User intent | Primary document | Optional deeper reference |
+| --- | --- | --- |
+| Overview, capabilities, install, quick start, command list, telemetry catalog | `package:README.md` | `package:docs/reference/01-requirements-and-scope.md` |
+| Project config creation, what to edit, credentials, precedence | `package:docs/configuration.md` | `package:docs/reference/12-configuration-reference.md` |
+| Exact config key, environment variable, validation rule, safe default | `package:docs/reference/12-configuration-reference.md` | `package:src/config/schema.ts` only for an implementation-level question or suspected documentation drift |
+| Privacy defaults, prompt/response/tool/Bash capture, redaction, hashing, paths, TLS | `package:SECURITY.md` | `package:docs/reference/06-security-privacy-redaction.md` |
+| Metrics, spans, log events, attributes, labels, cardinality | `package:README.md`, section `Available Telemetry` | `package:docs/reference/04-telemetry-semantic-conventions.md` |
+| OTLP endpoints, Collector processors/exporters, Tempo, Loki, Prometheus, Mimir | `package:examples/README.md` | `package:docs/reference/05-otel-pipeline-and-collector.md` |
+| Local example configuration | `package:examples/observme.yaml` | `package:docs/configuration.md` |
+| Production Collector example | `package:examples/collector.yaml` | `package:docs/reference/05-otel-pipeline-and-collector.md` |
+| `/obs status`, health, session, cost, trace, tools, errors, logs, agents, backfill | `package:README.md`, section `Commands` | `package:docs/reference/08-query-grafana-integration.md` |
+| Grafana auth, datasource UIDs, TLS/DNS, data visible but commands fail | `package:docs/validation-flow.md` | `package:docs/reference/08-query-grafana-integration.md` |
+| Dashboards, panel meaning, drill-downs, PromQL, LogQL, TraceQL, alerts, SLOs | `package:docs/reference/09-dashboards-alerts-slos.md` | `package:README.md`, section `Dashboards and Examples` |
+| Deployment, CI, outages, missing traces/logs/metrics | `package:docs/reference/11-deployment-runbooks.md` | `package:docs/validation-flow.md` |
+| Supported Pi, Node.js, OTEL, Collector, and Grafana-stack versions | `package:docs/compatibility-matrix.md` | `package:docs/reference/10-testing-release-operations.md` |
+| Architecture, lifecycle, extension boundary | `package:docs/reference/02-reference-architecture.md` | `package:docs/reference/07-extension-implementation-blueprint.md` |
+| Pi events, sessions, branches, compaction, recovery | `package:docs/reference/03-pi-event-and-session-model.md` | `package:docs/reference/pi-session-format.md` |
+| Integrating another Pi extension, orchestrator, subagent runner, process manager, or remote executor | `package:docs/extension-integration.md` | `package:examples/integrations/subagent-runner.ts` |
+| Root agents, subagents, tmux, lineage, trace propagation, wait/join | `package:docs/agent-subagent-observability-requirements.md` | `package:docs/reference/03-pi-event-and-session-model.md` |
+| Tests, validation, release, package checks | `package:docs/reference/10-testing-release-operations.md` | `package:docs/review-validation.md` |
+| Source assumptions and upstream documentation basis | `package:docs/reference/13-source-notes.md` | Read the cited upstream source only if the user asks for verification |
+| Security vulnerability reporting | `package:SECURITY.md` | None |
+
+## Answer workflow
+
+1. Classify the question using the routing table.
+2. Read the primary document completely enough to cover the relevant section. Follow only Markdown links that are necessary to resolve the question.
+3. Read the deeper reference when the primary document lacks exact details or the user asks for architecture, schema, or implementation depth.
+4. Answer the question directly, then cite the relevant package-relative file path and section heading.
+5. If the user asks only where something is documented, provide the shortest matching path and section without summarizing unrelated material.
+6. If documents conflict, say so. Prefer current user-facing behavior in `package:README.md` and `package:docs/` over design or contributor notes, and identify any apparent drift.
+7. Distinguish live telemetry from names marked reserved or registered but not yet recorded.
+
+## Safety and accuracy
+
+- Never request, print, or repeat Grafana tokens, OTLP tokens, passwords, hash salts, raw prompts, raw commands, or private paths.
+- Recommend environment variables or a trusted project `.env` for secrets; do not recommend putting credentials in YAML.
+- Keep content capture disabled by default. If explaining opt-in capture, keep redaction enabled and mention the hash-salt requirement.
+- Never suggest workflow, session, agent, trace, span, entry, or tool-call IDs as Prometheus labels.
+- Do not claim arbitrary subagent launchers are automatically correlated; full lineage requires an ObservMe-aware launcher and propagated context.
+- Do not invent commands, configuration keys, telemetry names, supported versions, or remediation steps. If the packaged documentation does not answer the question, state that limitation and point to the closest reference.

package/src/integration.ts

@@ -0,0 +1,134 @@
+export const OBSERVME_INTEGRATION_CHANNEL = "observme:integration:request";
+export const OBSERVME_INTEGRATION_VERSION = 1 as const;
+
+export type ObservMeIntegrationVersion = typeof OBSERVME_INTEGRATION_VERSION;
+export type ObservMeProcessEnvironment = Record<string, string | undefined>;
+export type ObservMeSpawnType = "command" | "tool" | "extension" | "unknown";
+export type ObservMeSpawnReason = "delegated_task" | "parallel_search" | "review" | "tool_wrapper" | "unknown";
+export type ObservMeAgentWaitReason = "dependency" | "rate_limit" | "child_running" | "unknown";
+export type ObservMeChildStatus = "starting" | "active" | "completed" | "failed" | "cancelled" | "orphaned";
+export type ObservMeJoinStatus = "completed" | "failed" | "cancelled" | "timeout" | "unknown" | "waiting";
+export type ObservMeIntegrationFailureReason =
+  | "session_unavailable"
+  | "spawn_not_found"
+  | "wait_not_found"
+  | "join_not_found"
+  | "operation_failed";
+
+export interface ObservMeIntegrationFailure {
+  readonly ok: false;
+  readonly reason: ObservMeIntegrationFailureReason;
+}
+
+export interface ObservMeIntegrationContext {
+  readonly workflowId: string;
+  readonly workflowRootAgentId: string;
+  readonly agentId: string;
+  readonly parentAgentId?: string;
+  readonly rootAgentId: string;
+  readonly depth: number;
+  readonly role: "root" | "subagent" | "orchestrator" | "worker" | "reviewer" | "unknown";
+  readonly capability?: string;
+  readonly sessionId?: string;
+  readonly traceId?: string;
+}
+
+export interface ObservMeIntegrationContextSuccess {
+  readonly ok: true;
+  readonly context: ObservMeIntegrationContext;
+}
+
+export interface ObservMeStartSubagentOptions {
+  readonly spawnId?: string;
+  readonly childAgentId?: string;
+  readonly command?: string;
+  readonly args?: readonly string[];
+  readonly spawnType?: ObservMeSpawnType;
+  readonly spawnReason?: ObservMeSpawnReason;
+  readonly toolCallId?: string;
+  readonly env?: ObservMeProcessEnvironment;
+}
+
+export interface ObservMeStartedSubagent {
+  readonly ok: true;
+  readonly spawnId: string;
+  readonly childAgentId: string;
+  readonly env: ObservMeProcessEnvironment;
+  readonly traceContextPropagated: boolean;
+}
+
+export interface ObservMeCompleteSubagentOptions {
+  readonly childAgentId?: string;
+  readonly childStatus?: ObservMeChildStatus;
+  readonly outcome?: "completed" | "failed" | "cancelled";
+}
+
+export interface ObservMeFailSubagentOptions {
+  readonly childAgentId?: string;
+  readonly errorClass?: string;
+}
+
+export interface ObservMeWaitJoinOptions {
+  readonly id?: string;
+  readonly spawnId?: string;
+  readonly childAgentId?: string;
+  readonly childStatus?: ObservMeChildStatus;
+  readonly joinStatus?: ObservMeJoinStatus;
+  readonly reason?: ObservMeAgentWaitReason;
+  readonly failurePropagated?: boolean;
+  readonly durationMs?: number;
+}
+
+export interface ObservMeStartedWaitJoin {
+  readonly ok: true;
+  readonly id: string;
+}
+
+export interface ObservMeIntegrationSuccess {
+  readonly ok: true;
+}
+
+export interface ObservMeIntegrationApi {
+  readonly version: ObservMeIntegrationVersion;
+  getContext(): ObservMeIntegrationContextSuccess | ObservMeIntegrationFailure;
+  startSubagent(options?: ObservMeStartSubagentOptions): ObservMeStartedSubagent | ObservMeIntegrationFailure;
+  completeSubagent(spawnId: string, options?: ObservMeCompleteSubagentOptions): ObservMeIntegrationSuccess | ObservMeIntegrationFailure;
+  failSubagent(spawnId: string, options?: ObservMeFailSubagentOptions): ObservMeIntegrationSuccess | ObservMeIntegrationFailure;
+  startWait(options?: ObservMeWaitJoinOptions): ObservMeStartedWaitJoin | ObservMeIntegrationFailure;
+  endWait(waitId: string, options?: ObservMeWaitJoinOptions): ObservMeIntegrationSuccess | ObservMeIntegrationFailure;
+  startJoin(options?: ObservMeWaitJoinOptions): ObservMeStartedWaitJoin | ObservMeIntegrationFailure;
+  endJoin(joinId: string, options?: ObservMeWaitJoinOptions): ObservMeIntegrationSuccess | ObservMeIntegrationFailure;
+}
+
+export interface ObservMeIntegrationRequest {
+  readonly supportedVersions: readonly ObservMeIntegrationVersion[];
+  readonly respond: (api: ObservMeIntegrationApi) => void;
+}
+
+export interface ObservMeIntegrationEventBus {
+  emit(channel: string, data: unknown): void;
+}
+
+export interface ObservMeIntegrationHost {
+  readonly events: ObservMeIntegrationEventBus;
+}
+
+interface IntegrationResponseHolder {
+  api?: ObservMeIntegrationApi;
+}
+
+export function requestObservMeIntegration(host: ObservMeIntegrationHost): ObservMeIntegrationApi | undefined {
+  const holder: IntegrationResponseHolder = {};
+  const request: ObservMeIntegrationRequest = {
+    supportedVersions: [OBSERVME_INTEGRATION_VERSION],
+    respond: receiveObservMeIntegration.bind(undefined, holder),
+  };
+
+  host.events.emit(OBSERVME_INTEGRATION_CHANNEL, request);
+  return holder.api;
+}
+
+function receiveObservMeIntegration(holder: IntegrationResponseHolder, api: ObservMeIntegrationApi): void {
+  if (api.version !== OBSERVME_INTEGRATION_VERSION || holder.api) return;
+  holder.api = api;
+}

package/src/pi/handlers.ts

@@ -3,6 +3,7 @@ import { registerLifecycleHandlers } from "./event-handlers/lifecycle.ts";
 import { registerLlmHandlers } from "./event-handlers/llm.ts";
 import { registerSessionEventHandlers } from "./event-handlers/session-events.ts";
 import { registerToolBashHandlers } from "./event-handlers/tool-bash.ts";
+import { registerObservMeIntegration } from "./integration-api.ts";
 import {
   HandlerRegistrar,
   SerializedLifecycleQueue,
@@ -71,5 +72,15 @@ export function registerHandlers(pi: unknown, options: RegisterHandlersOptions =
   registerLlmHandlers(registrar, state);
   registerToolBashHandlers(registrar, state);
   registerSessionEventHandlers(registrar, state);
+  registerIntegrationCleanup(registrar, registerObservMeIntegration(pi, state));
   registrar.commit();
 }
+
+function registerIntegrationCleanup(registrar: HandlerRegistrar, unsubscribe: (() => void) | undefined): void {
+  if (!unsubscribe) return;
+  registrar.add("session_shutdown", unsubscribeIntegration.bind(undefined, unsubscribe));
+}
+
+function unsubscribeIntegration(unsubscribe: () => void): void {
+  unsubscribe();
+}