@senad-d/observme 0.1.0

package/src/config/validate.ts

@@ -0,0 +1,456 @@
+import { Compile } from "typebox/compile";
+import { defaultObservMeConfig } from "./defaults.ts";
+import { observMeConfigSchema } from "./schema.ts";
+import type { ObservMeConfig } from "./schema.ts";
+import { validateCustomRedactionPatterns } from "../privacy/redact.ts";
+
+export interface ValidationIssue {
+  code: string;
+  message: string;
+}
+
+export interface ConfigValidationOptions {
+  env?: NodeJS.ProcessEnv;
+  isProjectTrusted?: boolean;
+  projectConfigWasRead?: boolean;
+}
+
+export interface ConfigValidationResult {
+  valid: boolean;
+  issues: ValidationIssue[];
+}
+
+export interface ConfigRejectionDiagnostic {
+  readonly issueCodes: readonly string[];
+  readonly issueCount: number;
+}
+
+export interface EnsuredObservMeConfig {
+  readonly config: ObservMeConfig;
+  readonly rejection?: ConfigRejectionDiagnostic;
+}
+
+export interface ConfigLogSink {
+  warn?: (message: string) => void;
+}
+
+export interface UnsafeCaptureWarningContext {
+  ui?: {
+    notify?: (message: string, level?: "warning" | "info" | "error") => void | Promise<void>;
+  };
+}
+
+const forbiddenMetricLabelPattern =
+  /(?:^|[._-])(?:(?:workflow|session|agent|parent|child|trace|span|entry|spawn|tool_call)(?:[._-]|$)|id$)/i;
+const lineageValuePattern = /^[A-Za-z0-9._:-]+$/;
+const traceIdPattern = /^[a-f0-9]{32}$/i;
+const spanIdPattern = /^[a-f0-9]{16}$/i;
+const maximumLineageValueLength = 128;
+const maximumQueueSize = 10_000;
+const maximumActiveRegistrySize = 100_000;
+const maximumStructuralIssueDetails = 5;
+const maximumConfigDiagnosticCodeInputs = 64;
+const maximumConfigDiagnosticIssueCount = 1_000_000;
+const unknownConfigValidationIssueCode = "unknown_config_validation_issue";
+const knownConfigValidationIssueCodes = new Set([
+  "invalid_config_shape",
+  "unsafe_capture_without_redaction",
+  "insecure_production_transport",
+  "invalid_signal_endpoint_path",
+  "high_cardinality_metric_label",
+  "custom_redaction_pattern_limit",
+  "custom_redaction_pattern_too_long",
+  "custom_redaction_pattern_unsupported_construct",
+  "custom_redaction_pattern_nested_quantifier",
+  "custom_redaction_pattern_empty_match",
+  "invalid_custom_redaction_pattern",
+  "untrusted_project_config_read",
+  "malformed_lineage_value",
+  "queue_size_exceeds_guardrail",
+]);
+const observMeConfigValidator = Compile(observMeConfigSchema);
+
+export function validateObservMeConfig(
+  config: ObservMeConfig,
+  options: ConfigValidationOptions = {},
+): ConfigValidationResult {
+  const structuralIssues = validateConfigStructure(config);
+  if (structuralIssues.length > 0) return { valid: false, issues: structuralIssues };
+
+  const issues = [
+    ...validateRedactionBoundary(config),
+    ...validateTransportSecurity(config),
+    ...validateSignalEndpoints(config),
+    ...validateMetricLabels(config),
+    ...validateCustomRedactionPatternConfig(config),
+    ...validateProjectTrust(options),
+    ...validateLineageEnvironment(config, options.env ?? process.env),
+    ...validateQueueGuardrails(config),
+  ];
+
+  return { valid: issues.length === 0, issues };
+}
+
+export function ensureValidObservMeConfig(
+  config: ObservMeConfig,
+  options: ConfigValidationOptions & { logger?: ConfigLogSink } = {},
+): ObservMeConfig {
+  return ensureValidObservMeConfigWithDiagnostics(config, options).config;
+}
+
+export function ensureValidObservMeConfigWithDiagnostics(
+  config: ObservMeConfig,
+  options: ConfigValidationOptions & { logger?: ConfigLogSink } = {},
+): EnsuredObservMeConfig {
+  const result = validateObservMeConfig(config, options);
+  if (result.valid) return { config };
+
+  const rejection = createConfigRejectionDiagnostic(result.issues);
+  logValidationRejection(rejection, options.logger);
+  return { config: structuredClone(defaultObservMeConfig), rejection };
+}
+
+export function createConfigRejectionDiagnostic(issues: readonly ValidationIssue[]): ConfigRejectionDiagnostic {
+  return normalizeConfigRejectionDiagnostic({
+    issueCodes: issues.map(issue => issue.code),
+    issueCount: issues.length,
+  });
+}
+
+export function normalizeConfigRejectionDiagnostic(
+  rejection: ConfigRejectionDiagnostic,
+): ConfigRejectionDiagnostic {
+  const rawIssueCodes = Array.isArray(rejection.issueCodes)
+    ? rejection.issueCodes.slice(0, maximumConfigDiagnosticCodeInputs)
+    : [];
+  const issueCodes = new Set<string>();
+
+  for (const code of rawIssueCodes) {
+    issueCodes.add(normalizeConfigValidationIssueCode(code));
+  }
+
+  return {
+    issueCodes: [...issueCodes],
+    issueCount: normalizeConfigDiagnosticIssueCount(rejection.issueCount, issueCodes.size),
+  };
+}
+
+function normalizeConfigValidationIssueCode(code: unknown): string {
+  return typeof code === "string" && knownConfigValidationIssueCodes.has(code)
+    ? code
+    : unknownConfigValidationIssueCode;
+}
+
+function normalizeConfigDiagnosticIssueCount(value: number, minimum: number): number {
+  if (!Number.isFinite(value)) return minimum;
+  return Math.max(minimum, Math.min(Math.trunc(value), maximumConfigDiagnosticIssueCount));
+}
+
+export function hasContentCaptureEnabled(config: ObservMeConfig): boolean {
+  return Object.values(config.capture).some(Boolean);
+}
+
+export async function emitUnsafeCaptureWarning(
+  config: ObservMeConfig,
+  ctx: UnsafeCaptureWarningContext,
+): Promise<boolean> {
+  if (!config.privacy.allowUnsafeCapture || !hasContentCaptureEnabled(config)) return false;
+
+  await ctx.ui?.notify?.(unsafeCaptureWarningMessage(config), "warning");
+  return true;
+}
+
+function validateConfigStructure(config: unknown): ValidationIssue[] {
+  if (observMeConfigValidator.Check(config)) return [];
+
+  try {
+    return buildStructuralValidationIssues(observMeConfigValidator.Errors(config));
+  } catch (error) {
+    return buildUnreadableStructuralValidationIssues(error);
+  }
+}
+
+function buildUnreadableStructuralValidationIssues(error: unknown): ValidationIssue[] {
+  return [
+    {
+      code: "invalid_config_shape",
+      message: `Configuration shape is invalid and could not be inspected safely (${formatStructuralInspectionFailure(error)}).`,
+    },
+  ];
+}
+
+function formatStructuralInspectionFailure(error: unknown): string {
+  if (error instanceof Error) return "schema validator threw an Error";
+  if (typeof error === "string") return "schema validator threw a string";
+  return "schema validator threw a non-error value";
+}
+
+function buildStructuralValidationIssues(errors: Array<{ keyword: string; instancePath: string }>): ValidationIssue[] {
+  const visibleErrors = errors.slice(0, maximumStructuralIssueDetails);
+  const issues = visibleErrors.map(error => ({
+    code: "invalid_config_shape",
+    message: formatStructuralValidationMessage(error),
+  }));
+
+  if (errors.length > visibleErrors.length) {
+    issues.push({
+      code: "invalid_config_shape",
+      message: `Configuration shape has ${errors.length - visibleErrors.length} additional structural issue(s).`,
+    });
+  }
+
+  return issues;
+}
+
+function formatStructuralValidationMessage(error: { keyword: string; instancePath: string }): string {
+  return `Configuration shape is invalid at ${formatSchemaPath(error.instancePath)}: ${describeSchemaKeyword(error.keyword)}.`;
+}
+
+function formatSchemaPath(instancePath: string): string {
+  if (!instancePath) return "root";
+  return instancePath.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+
+function describeSchemaKeyword(keyword: string): string {
+  if (keyword === "additionalProperties") return "unknown property is not allowed";
+  if (keyword === "required") return "required property is missing";
+  if (keyword === "type") return "value has an unsupported type";
+  if (keyword === "const" || keyword === "anyOf" || keyword === "enum") return "value is not one of the supported options";
+  if (keyword === "minimum" || keyword === "maximum") return "numeric value is outside the allowed range";
+  if (keyword === "minLength" || keyword === "maxLength") return "string length is outside the allowed range";
+  return `schema rule ${keyword} failed`;
+}
+
+function unsafeCaptureWarningMessage(config: ObservMeConfig): string {
+  if (config.privacy.redactionEnabled) {
+    return "ObservMe unsafe capture is active. Prompt, response, tool, bash, or path content may be exported after configured redaction.";
+  }
+
+  return "ObservMe unsafe capture is active with redaction disabled. Unredacted sensitive prompt, response, tool, bash, or path content may be exported.";
+}
+
+function validateRedactionBoundary(config: ObservMeConfig): ValidationIssue[] {
+  if (config.privacy.allowUnsafeCapture || config.privacy.redactionEnabled || !hasContentCaptureEnabled(config)) return [];
+
+  return [
+    {
+      code: "unsafe_capture_without_redaction",
+      message: "Content capture requires redaction unless privacy.allowUnsafeCapture is true.",
+    },
+  ];
+}
+
+function validateTransportSecurity(config: ObservMeConfig): ValidationIssue[] {
+  if (config.environment !== "production" || config.privacy.allowInsecureTransport) return [];
+
+  return [
+    ...validateProductionHttpEndpoint("otlp.endpoint", config.otlp.endpoint),
+    ...validateProductionHttpEndpoint("otlp.signalEndpoints.traces", config.otlp.signalEndpoints?.traces),
+    ...validateProductionHttpEndpoint("otlp.signalEndpoints.metrics", config.otlp.signalEndpoints?.metrics),
+    ...validateProductionHttpEndpoint("otlp.signalEndpoints.logs", config.otlp.signalEndpoints?.logs),
+    ...validateProductionHttpEndpoint("query.grafana.url", config.query.grafana.url),
+  ];
+}
+
+function validateProductionHttpEndpoint(name: string, endpoint: string | undefined): ValidationIssue[] {
+  if (!endpoint || !isHttpEndpoint(endpoint)) return [];
+
+  return [
+    {
+      code: "insecure_production_transport",
+      message: `${name} must not use http:// in production unless privacy.allowInsecureTransport is true.`,
+    },
+  ];
+}
+
+function isHttpEndpoint(endpoint: string): boolean {
+  return endpoint.trim().toLowerCase().startsWith("http://");
+}
+
+function validateSignalEndpoints(config: ObservMeConfig): ValidationIssue[] {
+  if (config.otlp.protocol !== "http/protobuf") return [];
+
+  const endpoints = config.otlp.signalEndpoints;
+  if (!endpoints) return [];
+
+  return [
+    ...validateSignalEndpoint("traces", endpoints.traces, "/v1/traces"),
+    ...validateSignalEndpoint("metrics", endpoints.metrics, "/v1/metrics"),
+    ...validateSignalEndpoint("logs", endpoints.logs, "/v1/logs"),
+  ];
+}
+
+function validateSignalEndpoint(signal: string, endpoint: string | undefined, requiredPath: string): ValidationIssue[] {
+  if (!endpoint || endpointPathMatches(endpoint, requiredPath)) return [];
+
+  return [
+    {
+      code: "invalid_signal_endpoint_path",
+      message: `${signal} OTLP HTTP exporter URL must include ${requiredPath}.`,
+    },
+  ];
+}
+
+function endpointPathMatches(endpoint: string, requiredPath: string): boolean {
+  try {
+    return new URL(endpoint).pathname.endsWith(requiredPath);
+  } catch {
+    return false;
+  }
+}
+
+function validateMetricLabels(config: ObservMeConfig): ValidationIssue[] {
+  const labels = config.metrics.labels ?? [];
+  return labels.filter(isForbiddenMetricLabel).map(label => ({
+    code: "high_cardinality_metric_label",
+    message: `Metric label ${label} is a forbidden high-cardinality identifier.`,
+  }));
+}
+
+function validateCustomRedactionPatternConfig(config: ObservMeConfig): ValidationIssue[] {
+  return validateCustomRedactionPatterns(config.privacy.customRedactionPatterns).map(issue => ({
+    code: issue.code,
+    message: issue.message,
+  }));
+}
+
+function isForbiddenMetricLabel(label: string): boolean {
+  return forbiddenMetricLabelPattern.test(label);
+}
+
+function validateProjectTrust(options: ConfigValidationOptions): ValidationIssue[] {
+  if (!options.projectConfigWasRead || options.isProjectTrusted !== false) return [];
+
+  return [
+    {
+      code: "untrusted_project_config_read",
+      message: "Project-local ObservMe config must not be read while ctx.isProjectTrusted() is false.",
+    },
+  ];
+}
+
+function validateLineageEnvironment(config: ObservMeConfig, env: NodeJS.ProcessEnv): ValidationIssue[] {
+  const allEnvironmentNames = configuredLineageEnvironmentNames(config);
+  const environmentNameIssues = validateLineageEnvironmentNames(allEnvironmentNames);
+  if (environmentNameIssues.length > 0) return environmentNameIssues;
+
+  const lineageEnvNames = [
+    config.workflow.idEnv,
+    config.agent.idEnv,
+    config.agent.parentIdEnv,
+    config.agent.rootIdEnv,
+    config.agent.parentSessionIdEnv,
+    config.agent.spawnIdEnv,
+    config.agent.capabilityEnv,
+  ];
+  const issues = lineageEnvNames.flatMap(name => validateLineageValue(name, env[name]));
+
+  return [
+    ...issues,
+    ...validateTraceValue(config.agent.parentTraceIdEnv, env[config.agent.parentTraceIdEnv]),
+    ...validateSpanValue(config.agent.parentSpanIdEnv, env[config.agent.parentSpanIdEnv]),
+    ...validateDepthValue(config.agent.depthEnv, env[config.agent.depthEnv]),
+  ];
+}
+
+function configuredLineageEnvironmentNames(config: ObservMeConfig): string[] {
+  return [
+    config.workflow.idEnv,
+    config.agent.idEnv,
+    config.agent.parentIdEnv,
+    config.agent.rootIdEnv,
+    config.agent.parentSessionIdEnv,
+    config.agent.parentTraceIdEnv,
+    config.agent.parentSpanIdEnv,
+    config.agent.depthEnv,
+    config.agent.spawnIdEnv,
+    config.agent.capabilityEnv,
+  ];
+}
+
+function validateLineageEnvironmentNames(names: string[]): ValidationIssue[] {
+  const normalizedNames = names.map(name => name.toUpperCase());
+  const uniqueNames = new Set(normalizedNames);
+  const malformed = names.some(name => !/^[A-Za-z_]\w{0,127}$/u.test(name));
+  const reserved = normalizedNames.some(name => name === "TRACEPARENT" || name === "TRACESTATE");
+  if (!malformed && !reserved && uniqueNames.size === names.length) return [];
+
+  return [
+    {
+      code: "malformed_lineage_value",
+      message: "Configured lineage environment variable names must be unique, safe, and distinct from W3C trace headers.",
+    },
+  ];
+}
+
+function validateLineageValue(envName: string, value: string | undefined): ValidationIssue[] {
+  if (!value) return [];
+  if (value.length <= maximumLineageValueLength && lineageValuePattern.test(value)) return [];
+
+  return [
+    {
+      code: "malformed_lineage_value",
+      message: `${envName} contains a malformed, oversized, or unsafe lineage value.`,
+    },
+  ];
+}
+
+function validateTraceValue(envName: string, value: string | undefined): ValidationIssue[] {
+  if (!value || (traceIdPattern.test(value) && !/^0{32}$/u.test(value))) return [];
+  return [{ code: "malformed_lineage_value", message: `${envName} must be a non-zero 32-character hex trace id.` }];
+}
+
+function validateSpanValue(envName: string, value: string | undefined): ValidationIssue[] {
+  if (!value || (spanIdPattern.test(value) && !/^0{16}$/u.test(value))) return [];
+  return [{ code: "malformed_lineage_value", message: `${envName} must be a non-zero 16-character hex span id.` }];
+}
+
+function validateDepthValue(envName: string, value: string | undefined): ValidationIssue[] {
+  if (!value) return [];
+  const parsed = Number(value);
+  if (Number.isInteger(parsed) && parsed >= 0 && parsed <= 64) return [];
+  return [{ code: "malformed_lineage_value", message: `${envName} must be an integer depth between 0 and 64.` }];
+}
+
+function validateQueueGuardrails(config: ObservMeConfig): ValidationIssue[] {
+  const queueChecks = [
+    ["traces.batch.maxQueueSize", config.traces.batch.maxQueueSize, maximumQueueSize],
+    ["logs.batch.maxQueueSize", config.logs.batch.maxQueueSize, maximumQueueSize],
+    ["limits.maxActiveAgentRuns", config.limits.maxActiveAgentRuns, maximumActiveRegistrySize],
+    ["limits.maxActiveTurns", config.limits.maxActiveTurns, maximumActiveRegistrySize],
+    ["limits.maxActiveToolCalls", config.limits.maxActiveToolCalls, maximumActiveRegistrySize],
+    ["limits.maxActiveLlmRequests", config.limits.maxActiveLlmRequests, maximumActiveRegistrySize],
+    ["limits.maxActiveSubagentSpawns", config.limits.maxActiveSubagentSpawns, maximumActiveRegistrySize],
+    ["limits.maxActiveAgentWaits", config.limits.maxActiveAgentWaits, maximumActiveRegistrySize],
+    ["limits.maxActiveAgentJoins", config.limits.maxActiveAgentJoins, maximumActiveRegistrySize],
+  ] as const;
+  const oversizeIssues = queueChecks.flatMap(([name, value, maximum]) => validateMaximumSize(name, value, maximum));
+
+  return [
+    ...oversizeIssues,
+    ...validateBatchSize("traces.batch.maxExportBatchSize", config.traces.batch.maxExportBatchSize, config.traces.batch.maxQueueSize),
+    ...validateBatchSize("logs.batch.maxExportBatchSize", config.logs.batch.maxExportBatchSize, config.logs.batch.maxQueueSize),
+  ];
+}
+
+function validateMaximumSize(name: string, value: number, maximum: number): ValidationIssue[] {
+  if (value <= maximum) return [];
+  return [{ code: "queue_size_exceeds_guardrail", message: `${name} exceeds memory guardrail ${maximum}.` }];
+}
+
+function validateBatchSize(name: string, value: number, queueSize: number): ValidationIssue[] {
+  if (value <= queueSize) return [];
+  return [{ code: "queue_size_exceeds_guardrail", message: `${name} must not exceed its maxQueueSize.` }];
+}
+
+function logValidationRejection(rejection: ConfigRejectionDiagnostic, logger: ConfigLogSink | undefined): void {
+  if (!logger?.warn) return;
+
+  try {
+    logger.warn(
+      `ObservMe config rejected (${rejection.issueCodes.join(", ")}); ${rejection.issueCount} issue(s), safe defaults applied.`,
+    );
+  } catch {
+    return;
+  }
+}

package/src/constants.ts

@@ -0,0 +1,4 @@
+// Branding constants for the ObservMe Pi extension.
+export const EXTENSION_DISPLAY_NAME = "ObservMe";
+export const EXTENSION_STATUS_KEY = "observme";
+export const EXTENSION_STATUS_VALUE = "🧿";

package/src/diagnostics/sanitize.ts

@@ -0,0 +1,6 @@
+export {
+  readDiagnosticMessage,
+  sanitizeUiDiagnosticText as sanitizeDiagnosticText,
+} from "../safety/sensitive-input.ts";
+
+export type { DiagnosticReplacement } from "../safety/sensitive-input.ts";

package/src/extension.ts

@@ -0,0 +1,38 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerObsCommand } from "./commands/obs.ts";
+import { registerHandlers } from "./pi/handlers.ts";
+
+const extensionPiApiCompatibilityErrorMessage =
+  "ObservMe/Pi API compatibility error: expected Pi ExtensionAPI with on(eventName, handler) and registerCommand(name, options) before registering ObservMe.";
+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 {
+  assertRegistrationApiAvailable(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 });
+  registerObsCommandWithPartialInitializationDiagnostic(pi);
+}
+
+function assertRegistrationApiAvailable(pi: ExtensionAPI): void {
+  const api = pi as Partial<ExtensionAPI> | null | undefined;
+
+  if (!api || typeof api.on !== "function" || typeof api.registerCommand !== "function") {
+    throw new TypeError(extensionPiApiCompatibilityErrorMessage);
+  }
+}
+
+function registerObsCommandWithPartialInitializationDiagnostic(pi: ExtensionAPI): void {
+  try {
+    registerObsCommand(pi);
+  } catch (error) {
+    throw createPartialInitializationError(error);
+  }
+}
+
+function createPartialInitializationError(cause: unknown): Error {
+  // Pi exposes pi.on/registerCommand but no unregister API for those registrations.
+  // If command registration fails after handler registration, ObservMe can only report the partial state.
+  return new Error(partialInitializationErrorMessage, { cause });
+}

package/src/otel/logs.ts

@@ -0,0 +1,160 @@
+import type { Logger } from "@opentelemetry/api-logs";
+import { createNoopLogger, logs } from "@opentelemetry/api-logs";
+import type { Resource } from "@opentelemetry/resources";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
+import type { LogRecordExporter, LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import type { LogsBatchConfig, ObservMeConfig } from "../config/schema.ts";
+import { appendOtlpSignalPath } from "./otlp-endpoint.ts";
+import type { StartOtelSdkFactoryOptions } from "./sdk.ts";
+
+export const OBSERVME_LOGGER_NAME = "@senad-d/observme";
+export const OTLP_LOG_SIGNAL_PATH = "/v1/logs";
+
+export const DOCUMENTED_LOG_BATCH_DEFAULTS = {
+  maxQueueSize: 2048,
+  maxExportBatchSize: 512,
+  scheduledDelayMillis: 1000,
+} satisfies LogsBatchConfig;
+
+export type LogPipelineState = "idle" | "disabled" | "started" | "shutdown";
+
+export interface OtlpLogExporterOptions {
+  readonly url: string;
+  readonly headers: Record<string, string>;
+  readonly timeoutMillis: number;
+}
+
+export interface LogProviderOptions {
+  readonly resource: Resource;
+  readonly processors: LogRecordProcessor[];
+  readonly forceFlushTimeoutMillis: number;
+}
+
+export interface LogProviderLike {
+  getLogger: (name: string) => Logger;
+  forceFlush?: () => Promise<void> | void;
+  shutdown?: () => Promise<void> | void;
+}
+
+export type LogExporterFactory = (options: OtlpLogExporterOptions) => LogRecordExporter;
+export type LogRecordProcessorFactory = (exporter: LogRecordExporter, options: LogsBatchConfig) => LogRecordProcessor;
+export type LogProviderFactory = (options: LogProviderOptions) => LogProviderLike;
+
+export interface ObservMeLogSdkOptions {
+  readonly config: ObservMeConfig;
+  readonly loggerName?: string;
+  readonly registerGlobal?: boolean;
+  readonly exporterFactory?: LogExporterFactory;
+  readonly processorFactory?: LogRecordProcessorFactory;
+  readonly loggerProviderFactory?: LogProviderFactory;
+}
+
+export interface LogExporterWiring {
+  readonly enabled: boolean;
+  readonly exporter: OtlpLogExporterOptions;
+  readonly batch: LogsBatchConfig;
+}
+
+const noopLogger = createNoopLogger();
+
+export class ObservMeLogSdk {
+  readonly #config: ObservMeConfig;
+  readonly #loggerName: string;
+  readonly #registerGlobal: boolean;
+  readonly #exporterFactory: LogExporterFactory;
+  readonly #processorFactory: LogRecordProcessorFactory;
+  readonly #loggerProviderFactory: LogProviderFactory;
+  #provider?: LogProviderLike;
+  #logger: Logger = noopLogger;
+  #state: LogPipelineState = "idle";
+
+  constructor(options: ObservMeLogSdkOptions) {
+    this.#config = options.config;
+    this.#loggerName = options.loggerName ?? OBSERVME_LOGGER_NAME;
+    this.#registerGlobal = options.registerGlobal ?? true;
+    this.#exporterFactory = options.exporterFactory ?? createOtlpLogExporter;
+    this.#processorFactory = options.processorFactory ?? createBatchLogRecordProcessor;
+    this.#loggerProviderFactory = options.loggerProviderFactory ?? createLogProvider;
+  }
+
+  get state(): LogPipelineState {
+    return this.#state;
+  }
+
+  get logger(): Logger {
+    return this.#logger;
+  }
+
+  start(): void {
+    if (this.#state === "started" || this.#state === "disabled") return;
+    if (!this.#config.logs.enabled) {
+      this.#state = "disabled";
+      return;
+    }
+
+    const wiring = buildLogExporterWiring(this.#config);
+    const exporter = this.#exporterFactory(wiring.exporter);
+    const processor = this.#processorFactory(exporter, wiring.batch);
+    this.#provider = this.#loggerProviderFactory({
+      resource: createLogResource(this.#config),
+      processors: [processor],
+      forceFlushTimeoutMillis: this.#config.shutdown.flushTimeoutMs,
+    });
+
+    if (this.#registerGlobal) logs.setGlobalLoggerProvider(this.#provider);
+    this.#logger = this.#provider.getLogger(this.#loggerName);
+    this.#state = "started";
+  }
+
+  async forceFlush(): Promise<void> {
+    await this.#provider?.forceFlush?.();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.#provider?.shutdown?.();
+    this.#state = "shutdown";
+    this.#logger = noopLogger;
+  }
+}
+
+export function createLogSessionScopedOtelSdk(options: StartOtelSdkFactoryOptions): ObservMeLogSdk {
+  return new ObservMeLogSdk({ config: options.config });
+}
+
+export function buildLogExporterWiring(config: ObservMeConfig): LogExporterWiring {
+  return {
+    enabled: config.logs.enabled,
+    exporter: buildOtlpLogExporterOptions(config),
+    batch: { ...config.logs.batch },
+  };
+}
+
+export function buildOtlpLogExporterOptions(config: ObservMeConfig): OtlpLogExporterOptions {
+  return {
+    url: resolveLogEndpoint(config),
+    headers: { ...config.otlp.headers },
+    timeoutMillis: config.otlp.timeoutMs,
+  };
+}
+
+export function resolveLogEndpoint(config: ObservMeConfig): string {
+  return config.otlp.signalEndpoints?.logs ?? appendOtlpSignalPath(config.otlp.endpoint, OTLP_LOG_SIGNAL_PATH);
+}
+
+function createOtlpLogExporter(options: OtlpLogExporterOptions): LogRecordExporter {
+  return new OTLPLogExporter(options);
+}
+
+function createBatchLogRecordProcessor(exporter: LogRecordExporter, options: LogsBatchConfig): LogRecordProcessor {
+  return new BatchLogRecordProcessor({ exporter, ...options });
+}
+
+function createLogProvider(options: LogProviderOptions): LogProviderLike {
+  return new LoggerProvider(options);
+}
+
+function createLogResource(config: ObservMeConfig): Resource {
+  return resourceFromAttributes(config.resource.attributes);
+}