@citeark/agent 0.3.20

package/src/observability/event-contract.mjs

@@ -0,0 +1,230 @@
+import { hasSessionEvents, sessionEvent } from '../terminal/events.mjs';
+const SENSITIVE_KEY = /^(?:authorization|cookie|set-cookie|password|secret|token|access[_-]?token|refresh[_-]?token|api[_-]?key|private[_-]?key)$/i;
+const SENSITIVE_QUERY_KEY = /(?:authorization|password|secret|token|api[_-]?key|signature|credential)/i;
+const BEARER_VALUE = /\b(?:bearer|basic)\s+[a-z0-9._~+/=-]+/gi;
+const SECRET_ASSIGNMENT = /\b(token|secret|password|api[_-]?key|authorization)=([^&\s]+)/gi;
+
+export const OBSERVABILITY_SCHEMA_VERSION = "1.0";
+
+export function sanitizeObservation(value, depth = 0) {
+  if (depth > 8) return "[depth-limited]";
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string") return redactText(value).slice(0, 4_000);
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) {
+    return value.slice(0, 100).map((item) => sanitizeObservation(item, depth + 1));
+  }
+  if (typeof value !== "object") return String(value).slice(0, 500);
+  const output = {};
+  for (const [key, item] of Object.entries(value).slice(0, 200)) {
+    output[key] = SENSITIVE_KEY.test(key)
+      ? "[REDACTED]"
+      : sanitizeObservation(item, depth + 1);
+  }
+  return output;
+}
+
+export function externalRequestObservation({
+  component,
+  service,
+  operation,
+  method = "GET",
+  url,
+  attempt,
+  maxAttempts,
+  startedAt,
+  finishedAt,
+  response,
+  error,
+  retryable = false,
+  correlation,
+}) {
+  const start = iso(startedAt) ?? new Date().toISOString();
+  const finish = iso(finishedAt) ?? start;
+  const status = Number.isInteger(response?.status) ? response.status : undefined;
+  return sanitizeObservation({
+    schemaVersion: OBSERVABILITY_SCHEMA_VERSION,
+    kind: "external_request",
+    component,
+    service,
+    operation,
+    correlation,
+    request: {
+      method: String(method).toUpperCase(),
+      url: observableUrl(url),
+      attempt,
+      maxAttempts,
+    },
+    response: status === undefined
+      ? undefined
+      : {
+          status,
+          requestId: firstHeader(response.headers, [
+            "x-github-request-id",
+            "x-request-id",
+            "x-goog-request-id",
+            "cf-ray",
+          ]),
+          retryAfter: header(response.headers, "retry-after"),
+          rateLimit: compact({
+            limit: header(response.headers, "x-ratelimit-limit"),
+            remaining: header(response.headers, "x-ratelimit-remaining"),
+            reset: header(response.headers, "x-ratelimit-reset"),
+            resource: header(response.headers, "x-ratelimit-resource"),
+          }),
+        },
+    outcome: {
+      status: response?.ok ? "succeeded" : "failed",
+      retryable: Boolean(retryable),
+      error: error
+        ? compact({
+            name: error instanceof Error ? error.name : "Error",
+            code: typeof error?.code === "string" ? error.code : undefined,
+            message: error instanceof Error ? error.message : String(error),
+          })
+        : undefined,
+    },
+    timing: {
+      startedAt: start,
+      finishedAt: finish,
+      durationMs: Math.max(0, Date.parse(finish) - Date.parse(start)),
+    },
+  });
+}
+
+export async function executeObservedExternalRequest({
+  request,
+  observe = emitStructuredObservation,
+  component,
+  service,
+  operation,
+  method = "GET",
+  url,
+  attempt = 1,
+  maxAttempts = 1,
+  retryableStatus = defaultRetryableStatus,
+  correlation,
+  now = () => new Date(),
+}) {
+  const startedAt = now().toISOString();
+  let response;
+  try {
+    response = await request();
+    safeObserve(observe, externalRequestObservation({
+      component,
+      service,
+      operation,
+      method,
+      url,
+      attempt,
+      maxAttempts,
+      startedAt,
+      finishedAt: now().toISOString(),
+      response,
+      error: response.ok ? undefined : new Error(`HTTP ${response.status}`),
+      retryable: retryableStatus(response.status),
+      correlation,
+    }));
+    return response;
+  } catch (error) {
+    safeObserve(observe, externalRequestObservation({
+      component,
+      service,
+      operation,
+      method,
+      url,
+      attempt,
+      maxAttempts,
+      startedAt,
+      finishedAt: now().toISOString(),
+      response,
+      error,
+      retryable: true,
+      correlation,
+    }));
+    throw error;
+  }
+}
+
+export function emitStructuredObservation(observation, {
+  severity,
+  output = console,
+} = {}) {
+  const safe = sanitizeObservation(observation);
+  const level = severity
+    ?? (safe?.outcome?.status === "failed" ? "WARNING" : "INFO");
+  const record = {
+    ...safe,
+    severity: level,
+    event: "citeark.observation",
+  };
+  if (output === console && hasSessionEvents()) {
+    sessionEvent({ kind: 'diagnostic', observation: record });
+    return record;
+  }
+  const target = level === "ERROR"
+    ? output.error
+    : level === "WARNING"
+      ? output.warn
+      : output.log;
+  target.call(output, JSON.stringify(record));
+  return record;
+}
+
+function observableUrl(value) {
+  try {
+    const url = new URL(String(value));
+    url.username = "";
+    url.password = "";
+    for (const key of [...url.searchParams.keys()]) {
+      if (SENSITIVE_QUERY_KEY.test(key)) url.searchParams.set(key, "[REDACTED]");
+    }
+    return url.toString();
+  } catch {
+    return redactText(String(value ?? ""));
+  }
+}
+
+function redactText(value) {
+  return String(value)
+    .replace(BEARER_VALUE, "[REDACTED_AUTHORIZATION]")
+    .replace(SECRET_ASSIGNMENT, "$1=[REDACTED]");
+}
+
+function header(headers, name) {
+  const value = headers?.get?.(name);
+  return typeof value === "string" && value ? value.slice(0, 500) : undefined;
+}
+
+function firstHeader(headers, names) {
+  for (const name of names) {
+    const value = header(headers, name);
+    if (value) return value;
+  }
+  return undefined;
+}
+
+function compact(value) {
+  const output = Object.fromEntries(
+    Object.entries(value).filter(([, item]) => item !== undefined && item !== null && item !== ""),
+  );
+  return Object.keys(output).length ? output : undefined;
+}
+
+function safeObserve(observe, observation) {
+  try {
+    observe(observation);
+  } catch {
+    // 日志接收器故障不能改变被观测请求的结果。
+  }
+}
+
+function defaultRetryableStatus(status) {
+  return new Set([408, 425, 429, 500, 502, 503, 504]).has(status);
+}
+
+function iso(value) {
+  if (value instanceof Date && Number.isFinite(value.getTime())) return value.toISOString();
+  if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) return undefined;
+  return new Date(value).toISOString();
+}

package/src/observability/pipeline-monitor.mjs

@@ -0,0 +1,166 @@
+import { sessionEvent } from '../terminal/events.mjs';
+import { appendFile, mkdir, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  OBSERVABILITY_SCHEMA_VERSION,
+  sanitizeObservation,
+} from "./event-contract.mjs";
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000;
+
+export function createPipelineMonitor({
+  directory,
+  pipelineId,
+  heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS,
+  now = () => new Date(),
+  correlation = {},
+  onEvent = () => {},
+} = {}) {
+  const root = path.join(path.resolve(directory), "observability");
+  const progressPath = path.join(root, "progress.json");
+  const eventsPath = path.join(root, "events.jsonl");
+  const startedAt = now().toISOString();
+  const safeCorrelation = sanitizeObservation(correlation);
+  const state = {
+    schemaVersion: OBSERVABILITY_SCHEMA_VERSION,
+    pipelineId,
+    correlation: safeCorrelation,
+    status: "running",
+    currentStage: null,
+    currentAction: "Initializing research",
+    startedAt,
+    updatedAt: startedAt,
+    lastHeartbeatAt: startedAt,
+    lastActivityAt: startedAt,
+    lastOutputAt: null,
+    sequence: 0,
+  };
+  let queue = Promise.resolve();
+  let closed = false;
+  let lastWriteError = null;
+
+  const enqueue = (operation) => {
+    queue = queue.then(operation, operation).catch((error) => {
+      lastWriteError = error;
+    });
+    return queue;
+  };
+
+  const persist = () => {
+    const snapshot = structuredClone(state);
+    enqueue(async () => {
+      await mkdir(root, { recursive: true });
+      await atomicJson(progressPath, snapshot);
+    });
+  };
+
+  const record = (message, {
+    kind = "activity",
+    level = "info",
+    stage = state.currentStage,
+    details = null,
+    output = false,
+  } = {}) => {
+    if (closed || typeof message !== "string" || !message.trim()) return null;
+    const at = now().toISOString();
+    const safeMessage = sanitizeObservation(message.trim());
+    const safeDetails = details && typeof details === "object"
+      ? sanitizeObservation(details)
+      : null;
+    state.sequence += 1;
+    state.currentStage = stage ?? state.currentStage;
+    state.currentAction = safeMessage;
+    state.updatedAt = at;
+    state.lastActivityAt = at;
+    if (output) state.lastOutputAt = at;
+    const event = {
+      schemaVersion: OBSERVABILITY_SCHEMA_VERSION,
+      pipelineId,
+      correlation: safeCorrelation,
+      sequence: state.sequence,
+      at,
+      kind,
+      level,
+      stage: state.currentStage,
+      message: safeMessage,
+      ...(safeDetails ? { details: safeDetails } : {}),
+    };
+    try {
+      onEvent(structuredClone(event));
+    } catch {
+      // 外部日志接收器故障不能改变流水线结果；本地事件仍会继续落盘。
+    }
+    const snapshot = structuredClone(state);
+    enqueue(async () => {
+      await mkdir(root, { recursive: true });
+      await appendFile(eventsPath, `${JSON.stringify(event)}\n`, "utf8");
+      await atomicJson(progressPath, snapshot);
+    });
+    return event;
+  };
+
+  const heartbeat = () => {
+    if (closed) return;
+    const at = now().toISOString();
+    state.updatedAt = at;
+    state.lastHeartbeatAt = at;
+    persist();
+  };
+
+  const timer = setInterval(heartbeat, Math.max(1_000, Number(heartbeatIntervalMs) || DEFAULT_HEARTBEAT_INTERVAL_MS));
+  timer.unref?.();
+
+  return {
+    paths: { root, progress: progressPath, events: eventsPath },
+    state,
+    async start({ stage = null, message = "Research started" } = {}) {
+      state.currentStage = stage;
+      record(message, { kind: "lifecycle", stage });
+      await queue;
+    },
+    record,
+    stage(stage, status, message, details = {}) {
+      sessionEvent({ kind: 'stage', stage, status });
+      state.currentStage = stage;
+      return record(message, {
+        kind: "stage",
+        level: status === "failed" ? "error" : "info",
+        stage,
+        details: { ...details, status },
+      });
+    },
+    output(message, options = {}) {
+      return record(message, { ...options, kind: options.kind ?? "agent-output", output: true });
+    },
+    heartbeat,
+    async flush() {
+      await queue;
+      return { error: lastWriteError };
+    },
+    async close({ status = "completed", stage = state.currentStage, message } = {}) {
+      clearInterval(timer);
+      if (closed) return { error: lastWriteError };
+      if (message) record(message, {
+        kind: "lifecycle",
+        level: status === "failed" ? "error" : "info",
+        stage,
+        details: { status },
+      });
+      state.status = status;
+      state.currentStage = stage;
+      state.updatedAt = now().toISOString();
+      state.lastHeartbeatAt = state.updatedAt;
+      persist();
+      closed = true;
+      await queue;
+      return { error: lastWriteError };
+    },
+  };
+}
+
+async function atomicJson(target, value) {
+  const temporary = `${target}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  await rename(temporary, target);
+}