@parall/agent-core 1.31.0 → 1.32.1

package/src/telemetry.ts

@@ -0,0 +1,252 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import {
+  trace,
+  metrics,
+  type Span,
+  type Tracer,
+  type Counter,
+  type Histogram,
+  SpanStatusCode,
+} from '@opentelemetry/api';
+import { type Logger, SeverityNumber } from '@opentelemetry/api-logs';
+import type { GatewayLogger } from './dispatch-adapter.js';
+import type { DispatchMetrics } from './session-state.js';
+import type { ParallEvent } from './types.js';
+
+let initialized = false;
+let shutdownFn: (() => Promise<void>) | null = null;
+
+let tracer: Tracer | null = null;
+let dispatchCounter: Counter | null = null;
+let dispatchDuration: Histogram | null = null;
+let missingReplyCounter: Counter | null = null;
+let otelLogger: Logger | null = null;
+
+function resolveTargetType(targetId: string): string {
+  if (targetId.startsWith('cht_')) return 'chat';
+  if (targetId.startsWith('tsk_')) return 'task';
+  if (targetId.startsWith('sch_')) return 'schedule';
+  return 'unknown';
+}
+
+export interface TelemetryHandle {
+  shutdown: () => Promise<void>;
+}
+
+/**
+ * Initialize agent telemetry. All agents export OTLP to the Parall
+ * telemetry-service (`PRLL_API_URL/otel`), authenticated with `PRLL_API_KEY`.
+ * The service canonicalizes identity from the token and proxies to SigNoz.
+ *
+ * Resource attributes include machine/agent/org identity from env.
+ * Returns a no-op handle when `PRLL_API_URL` is absent (local dev).
+ */
+export async function initAgentTelemetry(
+  serviceName: string,
+  runtimeType: string,
+): Promise<TelemetryHandle> {
+  const noopHandle: TelemetryHandle = { shutdown: async () => {} };
+
+  const apiUrl = process.env.PRLL_API_URL;
+  const apiKey = process.env.PRLL_API_KEY;
+  if (!apiUrl || !apiKey) {
+    return noopHandle;
+  }
+
+  try {
+    const otelEndpoint = apiUrl.replace(/\/$/, '') + '/otel';
+
+    const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-proto');
+    const { OTLPMetricExporter } = await import('@opentelemetry/exporter-metrics-otlp-proto');
+    const { OTLPLogExporter } = await import('@opentelemetry/exporter-logs-otlp-proto');
+    const { NodeTracerProvider, BatchSpanProcessor } = await import(
+      '@opentelemetry/sdk-trace-node'
+    );
+    const { MeterProvider, PeriodicExportingMetricReader } = await import(
+      '@opentelemetry/sdk-metrics'
+    );
+    const { LoggerProvider, BatchLogRecordProcessor } = await import('@opentelemetry/sdk-logs');
+    const { Resource } = await import('@opentelemetry/resources');
+
+    const resource = new Resource({
+      'service.name': serviceName,
+      'service.version': process.env.npm_package_version || 'unknown',
+      'deployment.environment.name':
+        process.env.PRLL_SERVER_ENV || process.env.NODE_ENV || 'development',
+      'parall.runtime_type': runtimeType,
+      'parall.agent_id': process.env.PRLL_AGENT_ID || '',
+      'parall.machine_id': process.env.PRLL_MACHINE_ID || '',
+      'parall.org_id': process.env.PRLL_ORG_ID || '',
+      'parall.daemon_mode': process.env.PRLL_DAEMON_MODE === '1',
+    });
+
+    const authHeaders = { Authorization: `Bearer ${apiKey}` };
+
+    const traceExporter = new OTLPTraceExporter({
+      url: `${otelEndpoint}/v1/traces`,
+      headers: authHeaders,
+    });
+    const tracerProvider = new NodeTracerProvider({ resource });
+    tracerProvider.addSpanProcessor(new BatchSpanProcessor(traceExporter));
+    tracerProvider.register();
+
+    const metricExporter = new OTLPMetricExporter({
+      url: `${otelEndpoint}/v1/metrics`,
+      headers: authHeaders,
+    });
+    const metricReader = new PeriodicExportingMetricReader({
+      exporter: metricExporter,
+      exportIntervalMillis: 15_000,
+    });
+    const meterProvider = new MeterProvider({ resource, readers: [metricReader] });
+    metrics.setGlobalMeterProvider(meterProvider);
+
+    const logExporter = new OTLPLogExporter({
+      url: `${otelEndpoint}/v1/logs`,
+      headers: authHeaders,
+    });
+    const loggerProvider = new LoggerProvider({ resource });
+    loggerProvider.addLogRecordProcessor(new BatchLogRecordProcessor(logExporter));
+
+    const meter = metrics.getMeter('parall.agent');
+    tracer = trace.getTracer('parall.agent');
+    otelLogger = loggerProvider.getLogger('parall.agent');
+    dispatchCounter = meter.createCounter('parall.dispatch.count', {
+      description: 'Number of dispatch cycles completed',
+    });
+    dispatchDuration = meter.createHistogram('parall.dispatch.duration', {
+      description: 'Dispatch cycle duration in milliseconds',
+      unit: 'ms',
+    });
+    missingReplyCounter = meter.createCounter('parall.dispatch.missing_reply', {
+      description: 'Dispatches where agent produced text but sent no reply message',
+    });
+
+    initialized = true;
+    shutdownFn = async () => {
+      await tracerProvider.forceFlush();
+      await meterProvider.forceFlush();
+      await loggerProvider.forceFlush();
+      await tracerProvider.shutdown();
+      await meterProvider.shutdown();
+      await loggerProvider.shutdown();
+    };
+
+    return {
+      shutdown: async () => {
+        if (shutdownFn) await shutdownFn();
+      },
+    };
+  } catch {
+    return noopHandle;
+  }
+}
+
+export function startDispatchSpan(
+  event: ParallEvent,
+  runtimeType: string,
+  sessionKey: string,
+): Span | null {
+  if (!initialized || !tracer) return null;
+  return tracer.startSpan('parall.dispatch', {
+    attributes: {
+      'dispatch.target_type': resolveTargetType(event.targetId),
+      'dispatch.event_type': event.type,
+      'dispatch.runtime_type': runtimeType,
+      'dispatch.session_key': sessionKey,
+      'dispatch.message_id': event.messageId,
+      'dispatch.target_id': event.targetId,
+    },
+  });
+}
+
+export function endDispatchSpan(
+  span: Span | null,
+  metricsSnapshot: DispatchMetrics | undefined,
+  error?: unknown,
+): void {
+  if (!span) return;
+  if (metricsSnapshot) {
+    span.setAttributes({
+      'dispatch.deliver_text_chunks': metricsSnapshot.deliver_text_chunks,
+      'dispatch.deliver_text_chars': metricsSnapshot.deliver_text_chars,
+      'dispatch.message_send_attempts': metricsSnapshot.message_send_attempts,
+      'dispatch.message_send_successes': metricsSnapshot.message_send_successes,
+      'dispatch.no_reply_called': metricsSnapshot.no_reply_called,
+      'dispatch.tool_call_count': metricsSnapshot.tool_call_count,
+      'dispatch.duration_ms': Date.now() - metricsSnapshot.started_at,
+    });
+  }
+  if (error) {
+    span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
+    span.recordException(error instanceof Error ? error : new Error(String(error)));
+  }
+  span.end();
+}
+
+export function recordDispatchMetric(
+  event: ParallEvent,
+  runtimeType: string,
+  durationMs: number,
+): void {
+  if (!initialized) return;
+  const attrs = {
+    target_type: resolveTargetType(event.targetId),
+    event_type: event.type,
+    runtime_type: runtimeType,
+  };
+  dispatchCounter?.add(1, attrs);
+  dispatchDuration?.record(durationMs, attrs);
+}
+
+export function recordMissingReply(runtimeType: string): void {
+  if (!initialized) return;
+  missingReplyCounter?.add(1, { runtime_type: runtimeType });
+}
+
+const sessionKeyStorage = new AsyncLocalStorage<string>();
+
+export function runWithSessionKey<T>(sessionKey: string, fn: () => T): T {
+  return sessionKeyStorage.run(sessionKey, fn);
+}
+
+/**
+ * Create a GatewayLogger that forwards all levels to OTLP logs.
+ * Two layers: "agent" (runtime) and "daemon".
+ */
+export function createOtelLogger(layer: 'agent' | 'daemon', prefix: string): GatewayLogger {
+  const ts = () => new Date().toISOString();
+  const emit = (severity: 'INFO' | 'WARN' | 'ERROR', msg: string) => {
+    if (!otelLogger) return;
+    const severityNumber =
+      severity === 'ERROR'
+        ? SeverityNumber.ERROR
+        : severity === 'WARN'
+          ? SeverityNumber.WARN
+          : SeverityNumber.INFO;
+    const attrs: Record<string, string> = { 'log.layer': layer, 'log.prefix': prefix };
+    const sk = sessionKeyStorage.getStore();
+    if (sk) attrs['session.key'] = sk;
+    otelLogger.emit({
+      severityNumber,
+      severityText: severity,
+      body: msg,
+      attributes: attrs,
+    });
+  };
+  return {
+    info: (msg: string) => {
+      console.log(`${ts()} [${prefix}] ${msg}`);
+      emit('INFO', msg);
+    },
+    warn: (msg: string) => {
+      console.warn(`${ts()} [${prefix}] ${msg}`);
+      emit('WARN', msg);
+    },
+    error: (msg: string) => {
+      console.error(`${ts()} [${prefix}] ${msg}`);
+      emit('ERROR', msg);
+    },
+    child: (sub: string) => createOtelLogger(layer, `${prefix}:${sub}`),
+  };
+}

package/src/types.ts

@@ -24,10 +24,17 @@ export type DispatchState = {
 
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-  type: "message" | "task" | "task_comment" | "schedule" | "approval";
+  type: 'message' | 'task' | 'task_comment' | 'wiki_comment' | 'schedule' | 'approval';
   targetId: string;
   targetName?: string;
   targetType?: string;
+  /**
+   * Full `prll://` target URI to reply on, used for wiki_comment events where
+   * the reply goes back to the same wiki page / changeset via
+   * `parall comments add --target <uri>`. Carried separately from `targetId`
+   * (a bare entity id) because the reply needs the full URI incl. path/anchor.
+   */
+  replyTargetUri?: string;
   deliveryReason?: string;
   senderId: string;
   senderName: string;
@@ -48,6 +55,15 @@ export type ParallEvent = {
   /** Original event timestamp (e.g., message.created_at). When present,
    *  input steps use this instead of server insertion time for ordering. */
   sentAt?: string;
-  ackSourceType?: "message" | "task_activity" | "comment" | "schedule_run";
+  ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run';
   ackSourceId?: string;
+  /** Unread message count in the target chat since agent's last interaction. */
+  unreadCount?: number;
+  /** Channel cursor: the last message ID the agent read. */
+  unreadSince?: string;
+  /** For thread replies: total replies and unread replies in the thread. */
+  threadReplyCount?: number;
+  threadUnreadCount?: number;
+  /** Thread cursor: the last reply ID the agent read in this thread. */
+  threadUnreadSince?: string;
 };