@senad-d/observme 0.1.0

package/ObservMe-Production-Docs/12-configuration-reference.md

@@ -0,0 +1,337 @@
+# ObservMe Configuration Reference
+
+## 1. Full Example
+
+```yaml
+observme:
+  enabled: true
+  environment: production
+  tenant: platform
+
+  otlp:
+    endpoint: https://otel-collector.example.com:4318   # base OTLP HTTP endpoint
+    protocol: http/protobuf
+    timeoutMs: 3000
+    headers:
+      Authorization: "Bearer ${OBSERVME_OTLP_TOKEN}"
+    tls:
+      enabled: true
+      insecureSkipVerify: false
+    # Derived SDK URLs for OTLP/HTTP exporters:
+    # traces:  https://otel-collector.example.com:4318/v1/traces
+    # metrics: https://otel-collector.example.com:4318/v1/metrics
+    # logs:    https://otel-collector.example.com:4318/v1/logs
+
+  resource:
+    attributes:
+      service.name: observme-pi-extension
+      observme.tenant.id: platform
+      pi.project.name: my-project
+      deployment.environment.name: production
+
+  workflow:
+    idEnv: OBSERVME_WORKFLOW_ID
+    enabled: true
+    maxDepthWarning: 5
+    maxFanoutWarning: 20
+
+  agent:
+    # Generated when absent. Parent/root values are accepted only from trusted
+    # process environment or explicit runtime options.
+    idEnv: OBSERVME_AGENT_ID
+    parentIdEnv: OBSERVME_PARENT_AGENT_ID
+    rootIdEnv: OBSERVME_ROOT_AGENT_ID
+    parentSessionIdEnv: OBSERVME_PARENT_SESSION_ID
+    parentTraceIdEnv: OBSERVME_PARENT_TRACE_ID
+    parentSpanIdEnv: OBSERVME_PARENT_SPAN_ID
+    depthEnv: OBSERVME_AGENT_DEPTH
+    spawnIdEnv: OBSERVME_SPAWN_ID
+    propagateTraceContext: true
+    propagateToSubagents: true
+    capabilityEnv: OBSERVME_AGENT_CAPABILITY
+    writeCorrelationEntry: false
+
+  traces:
+    enabled: true
+    sampleRatio: 1.0
+    batch:
+      maxQueueSize: 2048
+      maxExportBatchSize: 512
+      scheduledDelayMillis: 1000
+      exportTimeoutMillis: 3000
+
+  metrics:
+    enabled: true
+    exportIntervalMillis: 15000
+    exportTimeoutMillis: 3000
+
+  logs:
+    enabled: true
+    batch:
+      maxQueueSize: 2048
+      maxExportBatchSize: 512
+      scheduledDelayMillis: 1000
+
+  capture:
+    prompts: false
+    responses: false
+    thinking: false
+    toolArguments: false
+    toolResults: false
+    bashCommands: false
+    bashOutput: false
+    filePaths: false
+
+  privacy:
+    redactionEnabled: true
+    allowUnsafeCapture: false
+    allowInsecureTransport: false
+    tenantSaltEnv: OBSERVME_HASH_SALT
+    pathMode: hash
+    customRedactionPatterns:
+      - name: internal-token
+        pattern: "(?i)internal_token=[a-z0-9-]+"
+
+  limits:
+    maxPromptChars: 12000
+    maxResponseChars: 12000
+    maxToolArgumentChars: 8000
+    maxToolResultChars: 16000
+    maxBashOutputChars: 16000
+    maxLogBodyChars: 32000
+    maxActiveAgentRuns: 16
+    maxActiveTurns: 128
+    maxActiveToolCalls: 1024
+    maxActiveLlmRequests: 128
+    maxActiveSubagentSpawns: 128
+    maxActiveAgentWaits: 128
+    maxActiveAgentJoins: 128
+
+  query:
+    enabled: true
+    timeoutMs: 5000
+    maxLogs: 50
+    maxTraces: 20
+    maxMetricSeries: 20
+    maxAgents: 20
+    links:
+      traceUrlTemplate: "https://grafana.example.com/explore?left=..."
+    grafana:
+      url: https://grafana.example.com
+      token: ${OBSERVME_GRAFANA_TOKEN}
+      username: ""
+      password: ""
+      datasourceUids:
+        tempo: tempo
+        loki: loki
+        prometheus: mimir
+      tls:
+        insecureSkipVerify: false
+      transport:
+        preferIPv4: false
+
+  shutdown:
+    flushTimeoutMs: 3000
+```
+
+## 2. Environment Variables
+
+```text
+OBSERVME_ENABLED
+OBSERVME_ENVIRONMENT
+OBSERVME_TENANT
+OBSERVME_OTLP_ENDPOINT
+OBSERVME_OTLP_PROTOCOL
+OBSERVME_OTLP_TRACES_ENDPOINT
+OBSERVME_OTLP_METRICS_ENDPOINT
+OBSERVME_OTLP_LOGS_ENDPOINT
+OBSERVME_OTLP_TOKEN
+OBSERVME_WORKFLOW_ID
+OBSERVME_WORKFLOW_MAX_DEPTH_WARNING
+OBSERVME_WORKFLOW_MAX_FANOUT_WARNING
+OBSERVME_AGENT_ID
+OBSERVME_PARENT_AGENT_ID
+OBSERVME_ROOT_AGENT_ID
+OBSERVME_PARENT_SESSION_ID
+OBSERVME_PARENT_TRACE_ID
+OBSERVME_PARENT_SPAN_ID
+OBSERVME_AGENT_DEPTH
+OBSERVME_SPAWN_ID
+OBSERVME_AGENT_CAPABILITY
+OBSERVME_PROPAGATE_TRACE_CONTEXT
+OBSERVME_PROPAGATE_TO_SUBAGENTS
+OBSERVME_WRITE_CORRELATION_ENTRY
+OBSERVME_GRAFANA_URL
+OBSERVME_GRAFANA_TOKEN
+OBSERVME_GRAFANA_USERNAME
+OBSERVME_GRAFANA_PASSWORD
+OBSERVME_GRAFANA_TEMPO_DATASOURCE_UID
+OBSERVME_GRAFANA_LOKI_DATASOURCE_UID
+OBSERVME_GRAFANA_PROMETHEUS_DATASOURCE_UID
+OBSERVME_GRAFANA_TLS_INSECURE_SKIP_VERIFY
+OBSERVME_GRAFANA_PREFER_IPV4
+OBSERVME_HASH_SALT
+OBSERVME_CAPTURE_PROMPTS
+OBSERVME_CAPTURE_RESPONSES
+OBSERVME_CAPTURE_TOOL_ARGUMENTS
+OBSERVME_CAPTURE_TOOL_RESULTS
+OBSERVME_CAPTURE_THINKING
+OBSERVME_CAPTURE_BASH_COMMANDS
+OBSERVME_CAPTURE_BASH_OUTPUT
+OBSERVME_CAPTURE_FILE_PATHS
+OBSERVME_REDACTION_ENABLED
+OBSERVME_ALLOW_UNSAFE_CAPTURE
+OBSERVME_ALLOW_INSECURE_TRANSPORT
+```
+
+## 3. Workflow and Agent Lineage Configuration
+
+The `workflow:` and `agent:` config blocks control generated workflow identity, generated agent identity, and parent/child propagation. `pi.workflow.id`, `pi.agent.id`, `pi.agent.parent_id`, and related values are high-cardinality identifiers for traces/logs only; they must not be metric labels by default.
+
+Rules:
+
+- Generate a random `pi.agent.id` and `pi.workflow.id` when no trusted value is supplied.
+- For root agents, set `pi.agent.root_id = pi.agent.id`, `pi.workflow.root_agent_id = pi.agent.id`, and `pi.agent.depth = 0`.
+- For subagents, accept parent/root/depth values only from the Pi process environment supplied by a trusted ObservMe-aware launcher or from explicit runtime overrides. Project-local `.env` values may configure ObservMe but must not establish lineage provenance.
+- Require a complete validated workflow, parent agent, root agent, depth, and spawn envelope. When `propagateTraceContext` is true, also require a valid W3C `traceparent`; validate optional `tracestate` and require duplicate parent trace/span metadata to match it.
+- Reject partial, malformed, oversized, or stale propagation fail-open: generate root/orphan identity, emit only bounded sanitized failure telemetry, and never include rejected raw environment values.
+- Continue a valid W3C parent context explicitly on the child `pi.session` span. If trusted lineage has no usable continuation, start a new trace and add a validated parent span link when metadata exists, otherwise emit the documented propagation-failure log/counter fallback.
+- When `propagateTraceContext` is true, propagate W3C `traceparent`/`tracestate` to child processes launched by ObservMe-aware subagent wrappers.
+- When `workflow.enabled` is true, propagate `OBSERVME_WORKFLOW_ID` to child processes and report depth/fan-out/orphan metrics.
+- `writeCorrelationEntry` may append a minimal `custom` session entry for recovery, but it must remain disabled by default and must never use `custom_message`.
+
+## 4. Config Precedence
+
+1. Defaults
+2. Global config (`~/.pi/agent/observme.yaml`)
+3. Project config (`<cwd>/<CONFIG_DIR_NAME>/observme.yaml`, normally `.pi/observme.yaml`) only when `ctx.isProjectTrusted()` is true
+4. Project env file (`<cwd>/.env`) only when `ctx.isProjectTrusted()` is true
+5. System environment variables
+6. Explicit runtime options
+
+Copy `.env.example` to `.env` for project-local extension variables, or export the same `OBSERVME_*` names in the shell before starting Pi. System environment variables override `.env` values, and `.env` must never be committed. If redacted content capture is enabled, set `OBSERVME_HASH_SALT` in the shell or trusted project `.env`; missing salts make capture fail closed.
+
+Automatic project starter file:
+
+- On `session_start`, the extension creates `<cwd>/<CONFIG_DIR_NAME>/observme.yaml` (`<cwd>/.pi/observme.yaml` in the standard distribution) when the project is trusted and the file is missing.
+- The target is resolved as an absolute contained project path before mutation. The complete existence-check/create/write window uses Pi's per-file mutation queue, so concurrent starts create at most one starter.
+- Existing project config is never overwritten.
+- Edit the resolved project `observme.yaml` for custom setup: `otlp.endpoint` / signal-specific endpoints for the Collector, `resource.attributes` for service/project/tenant/environment labels, `capture` and `privacy` for content capture and redaction, and `query.grafana` / `query.links.traceUrlTemplate` for `/obs` query commands.
+- The generated starter mirrors the privacy-preserving local profile; raw content capture is disabled, redaction is enabled, and unsafe capture is disabled.
+- Keep credentials out of YAML. Reference environment variables in YAML and set secrets through the shell or a trusted project `.env`.
+- Use `~/.pi/agent/observme.yaml` only for standard-distribution global defaults that should apply across projects; project `<CONFIG_DIR_NAME>/observme.yaml` overrides it after trust.
+
+## 5. Safe Production Defaults
+
+```yaml
+capture:
+  prompts: false
+  responses: false
+  thinking: false
+  toolArguments: false
+  toolResults: false
+  bashCommands: false
+  bashOutput: false
+  filePaths: false
+privacy:
+  redactionEnabled: true
+  allowUnsafeCapture: false
+  allowInsecureTransport: false
+agent:
+  propagateTraceContext: true
+  propagateToSubagents: true
+  writeCorrelationEntry: false
+workflow:
+  enabled: true
+```
+
+## 6. Development Defaults
+
+```yaml
+otlp:
+  endpoint: http://localhost:4318
+  protocol: http/protobuf
+privacy:
+  redactionEnabled: true
+  allowInsecureTransport: true  # development localhost only
+capture:
+  prompts: false
+  responses: false
+```
+
+## 7. Local Grafana Query Development
+
+For the bundled `observability-stack/`, the supported `/obs` command path is authenticated Grafana through nginx HTTPS at `https://observability.local`. The default stack does not publish Grafana on `localhost:3000`; use a direct `http://127.0.0.1:<port>` Grafana URL only for tests or a custom Compose override.
+
+```yaml
+query:
+  enabled: true
+  links:
+    traceUrlTemplate: https://observability.local/explore?left=...
+  grafana:
+    url: https://observability.local
+    token: ${OBSERVME_GRAFANA_TOKEN}      # preferred service-account/bearer token
+    username: admin                       # local Basic auth fallback
+    password: ${OBSERVME_GRAFANA_PASSWORD}
+    datasourceUids:
+      tempo: tempo
+      loki: loki
+      prometheus: prometheus
+    tls:
+      insecureSkipVerify: true            # local self-signed cert only
+    transport:
+      preferIPv4: true                    # avoids observability.local IPv6 stalls
+```
+
+Rules:
+
+- Create a Grafana service-account token with Viewer access for read-only datasource queries and export it as `OBSERVME_GRAFANA_TOKEN`, or export/set `OBSERVME_GRAFANA_PASSWORD` from `observability-stack/secrets/grafana_admin_password` for local Basic auth. These values may come from system environment variables or a trusted project `.env` copied from `.env.example`.
+- Browser login cookies are not used by the extension; `/obs` commands call the Grafana API directly from the Pi process.
+- A resolved `query.grafana.token` is sent as `Authorization: Bearer ...` and takes precedence.
+- When the token is blank or an unresolved placeholder, a resolved `query.grafana.username` and `query.grafana.password` are sent as Basic auth for local development.
+- Query-backed commands and `/obs health` must fail fast before Grafana calls when Grafana auth is unresolved/missing/incomplete, `query.grafana.url` is invalid, or a required datasource UID is blank.
+- `/obs health` must report Grafana `401`/`403` responses as authentication failures and must not print token or password values.
+- `tls.insecureSkipVerify=true` is only for local self-signed certificates; production should trust the CA instead.
+- `transport.preferIPv4=true` uses Node's local HTTP(S) transport with IPv4 DNS lookup for Grafana calls.
+- Provisioned datasource UIDs are `tempo`, `loki`, and `prometheus`; Loki selectors use normalized labels such as `service_name`, `pi_session_id`, `event_name`, and `event_category` for ObservMe data.
+
+## 8. Unsafe Debug Mode
+
+Unsafe mode must require explicit opt-in:
+
+```yaml
+privacy:
+  allowUnsafeCapture: true
+capture:
+  prompts: true
+  responses: true
+  thinking: true
+  toolArguments: true
+  toolResults: true
+```
+
+To show redacted LLM chat content in Grafana Tempo and Loki, set `OBSERVME_CAPTURE_PROMPTS=true`, `OBSERVME_CAPTURE_RESPONSES=true`, `OBSERVME_CAPTURE_THINKING=true`, keep `OBSERVME_REDACTION_ENABLED=true`, and set `OBSERVME_HASH_SALT` before the conversation occurs. To show failed-tool output in the Tools dashboard, set `OBSERVME_CAPTURE_TOOL_RESULTS=true` with the same redaction and hash-salt safeguards; successful tool results remain span-only while failed output is emitted to the dedicated `tool.error.captured` Loki stream. Set `OBSERVME_ALLOW_UNSAFE_CAPTURE=true` only when redaction is disabled for intentionally raw local debugging. Dashboards show only new events emitted after these settings and the updated Collector are active; older data dropped by the Collector cannot be recovered.
+
+ObservMe must display a warning when unsafe capture is active. Redacted capture must pass all configured redactors, and raw unsafe capture is permitted only when redaction is explicitly disabled with a separately validated exception.
+
+## 9. Validation Rules
+
+Reject config when:
+
+- `allowUnsafeCapture=false` and `redactionEnabled=false` while any content capture is true.
+- Production endpoint uses `http://` and `allowInsecureTransport` is not true.
+- `otlp.protocol=http/protobuf` but a signal-specific exporter URL omits the required `/v1/traces`, `/v1/metrics`, or `/v1/logs` path.
+- Metric labels include high-cardinality fields such as workflow IDs, session IDs, agent IDs, parent/child agent IDs, trace IDs, span IDs, entry IDs, spawn IDs, or spawn tool-call IDs.
+- Project-local config is read while `ctx.isProjectTrusted()` is false.
+- Propagated workflow or agent lineage values are malformed, too long, or contain unsafe characters.
+- Queue sizes exceed configured memory guardrails.
+
+## 10. Minimal Config
+
+```yaml
+observme:
+  otlp:
+    endpoint: http://localhost:4318
+```
+
+Everything else uses safe defaults.

package/ObservMe-Production-Docs/13-source-notes.md

@@ -0,0 +1,33 @@
+# ObservMe Source Notes
+
+This document captures external technical assumptions referenced by the design and the official documentation sources used for cross-checking.
+
+## Pi
+
+- Pi extension lifecycle, event names, command registration, `ExtensionContext`, `ExtensionCommandContext`, and tool hooks are based on the official Pi `docs/extensions.md` documentation.
+- Pi extension factories may run before any session starts and may run in invocations that never start a session; background resources such as exporter timers must therefore be started from `session_start` and cleaned up from `session_shutdown`.
+- Pi session JSONL format, entry types, tree behavior, and `SessionManager` APIs are based on the official Pi `docs/session-format.md`, `docs/sessions.md`, and `docs/compaction.md` documentation plus installed TypeScript declarations under `@earendil-works/pi-coding-agent/dist/`.
+- Important event names used by ObservMe include `session_start`, `agent_start`, `agent_end`, `turn_start`, `before_provider_request`, `after_provider_response`, `message_start/update/end`, `tool_execution_start/update/end`, `tool_call`, `tool_result`, `user_bash`, `model_select`, `thinking_level_select`, `session_compact`, `session_tree`, and `session_shutdown`.
+- Pi exposes `ctx.isProjectTrusted()` and `CONFIG_DIR_NAME`; ObservMe project-local config must use these instead of hardcoding `.pi` or reading untrusted project config.
+- Pi does not expose a dedicated built-in "subagent spawned" lifecycle event. Workflow/agent/subagent lineage in ObservMe is an extension-level concern implemented by wrapping subagent launch/wait/join points and propagating W3C trace context plus ObservMe workflow/lineage environment variables.
+
+## OpenTelemetry
+
+- OpenTelemetry Collector receives, processes, and exports traces, metrics, and logs through configurable pipelines of receivers, processors, exporters, and service pipelines.
+- OTLP is the preferred protocol between ObservMe and the Collector.
+- OTLP/HTTP uses signal paths such as `/v1/traces`, `/v1/metrics`, and `/v1/logs`; OpenTelemetry JS exporters may require signal-specific `url` values even when ObservMe config stores a base endpoint.
+- Collector use is recommended for production because it centralizes batching, retries, filtering, routing, sampling, authentication, and backend decoupling.
+- Advanced Collector components such as `prometheusremotewrite`, `probabilistic_sampler`, and `tail_sampling` may require the Collector Contrib distribution or a vendor distribution.
+- OpenTelemetry GenAI semantic conventions define `gen_ai.*` attributes and metrics for model/client/agent telemetry. In the OpenTelemetry JS semantic-conventions package these GenAI constants are experimental/evolving, so ObservMe also keeps stable `observme_*` product metrics and `pi.*` domain attributes.
+- Current GenAI attributes include `gen_ai.agent.id`, `gen_ai.agent.name`, `gen_ai.agent.version`, `gen_ai.tool.*`, `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.usage.*`, and metrics such as `gen_ai.client.operation.duration` and `gen_ai.client.token.usage`.
+- W3C trace context (`traceparent`/`tracestate`) is the standard way to propagate parent trace identity across subagent process boundaries; if propagation is unavailable, ObservMe should record span links or equivalent log attributes. ObservMe's `pi.workflow.*` attributes are extension-defined correlation fields for orchestrator/agent-tree drill-down and are not official OTEL semantic conventions.
+- `deployment.environment.name` is the official OpenTelemetry deployment-environment resource attribute; `observme.environment` is only a compatibility alias.
+- `service.instance.id` and `observme.instance.id` identify an ObservMe telemetry session/process startup; they do not replace `pi.workflow.id` or `pi.agent.id` for logical workflow and parent/child agent lineage.
+
+## Grafana Stack
+
+- Tempo is the reference trace backend and accepts OTLP spans through gRPC or HTTP endpoints such as `/v1/traces` for OTLP/HTTP.
+- Loki is the reference log backend and can ingest OpenTelemetry logs through the OTLP HTTP endpoint using the Collector `otlphttp` exporter with an endpoint such as `http://loki:3100/otlp`.
+- Loki stores many OTLP attributes as structured metadata and normalizes dots to underscores for queries, for example `event.name` -> `event_name`, `pi.session.id` -> `pi_session_id`, `pi.workflow.id` -> `pi_workflow_id`, and `pi.agent.id` -> `pi_agent_id`.
+- Prometheus can receive OTLP metrics over HTTP only when started with `--web.enable-otlp-receiver`; the base endpoint is `/api/v1/otlp`, while explicit signal URLs use `/api/v1/otlp/v1/metrics`.
+- Mimir is the reference production-scale Prometheus-compatible metrics backend; Collector remote write to Mimir uses endpoints such as `/api/v1/push`.