chainlesschain 0.162.171 → 0.162.173

package/src/lib/metrics-collector.js

@@ -0,0 +1,127 @@
+/**
+ * MetricsCollector - CLI runtime metrics collection (M3)
+ *
+ * Collects counters, gauges, histograms for performance monitoring
+ * with OTLP export support (M8 integration)
+ */
+
+export class MetricsCollector {
+  constructor() {
+    this._counters = new Map();
+    this._gauges = new Map();
+    this._histograms = new Map();
+  }
+
+  /**
+   * Increment a counter metric
+   * @param {string} name - Metric name
+   * @param {number} value - Increment amount (default 1)
+   * @param {object} labels - Metric labels
+   */
+  counter(name, value = 1, labels = {}) {
+    const key = this._key(name, labels);
+    if (!this._counters.has(key)) {
+      this._counters.set(key, { name, value: 0, labels });
+    }
+    this._counters.get(key).value += value;
+  }
+
+  /**
+   * Set a gauge metric
+   * @param {string} name - Metric name
+   * @param {number} value - Gauge value
+   * @param {object} labels - Metric labels
+   */
+  gauge(name, value, labels = {}) {
+    const key = this._key(name, labels);
+    this._gauges.set(key, { name, value, labels, timestamp: Date.now() });
+  }
+
+  /**
+   * Record a histogram observation
+   * @param {string} name - Metric name
+   * @param {number} value - Observed value
+   * @param {object} labels - Metric labels
+   */
+  histogram(name, value, labels = {}) {
+    const key = this._key(name, labels);
+    if (!this._histograms.has(key)) {
+      this._histograms.set(key, {
+        name,
+        count: 0,
+        sum: 0,
+        min: Infinity,
+        max: -Infinity,
+        labels,
+        values: [],
+      });
+    }
+    const h = this._histograms.get(key);
+    h.count++;
+    h.sum += value;
+    h.min = Math.min(h.min, value);
+    h.max = Math.max(h.max, value);
+    // Keep last 1000 values for percentile calculation
+    if (h.values.length < 1000) {
+      h.values.push(value);
+    } else {
+      h.values[h.count % 1000] = value;
+    }
+  }
+
+  /**
+   * Time a function execution and record duration
+   * @param {string} name - Metric name
+   * @param {Function} fn - Function to time
+   * @param {object} labels - Metric labels
+   * @returns {*} Function result
+   */
+  async timer(name, fn, labels = {}) {
+    const start = performance.now();
+    try {
+      return await fn();
+    } finally {
+      const duration = performance.now() - start;
+      this.histogram(name, duration, labels);
+    }
+  }
+
+  /**
+   * Get all collected metrics
+   * @returns {object} All metrics
+   */
+  snapshot() {
+    return {
+      counters: Array.from(this._counters.values()),
+      gauges: Array.from(this._gauges.values()),
+      histograms: Array.from(this._histograms.values()).map((h) => ({
+        name: h.name,
+        count: h.count,
+        sum: h.sum,
+        min: h.min,
+        max: h.max,
+        avg: h.sum / h.count,
+        labels: h.labels,
+      })),
+    };
+  }
+
+  /**
+   * Reset all metrics
+   */
+  reset() {
+    this._counters.clear();
+    this._gauges.clear();
+    this._histograms.clear();
+  }
+
+  _key(name, labels) {
+    const labelStr = Object.entries(labels)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, v]) => `${k}=${v}`)
+      .join(",");
+    return labelStr ? `${name}{${labelStr}}` : name;
+  }
+}
+
+export const metricsCollector = new MetricsCollector();

package/src/lib/observability/index.js

@@ -0,0 +1,35 @@
+/**
+ * Observability - 可观测性模块统一导出
+ * M3 阶段模块：包含分布式追踪 + 性能指标收集
+ */
+
+import {
+  traceContext,
+  TraceContext,
+} from "../execution-trace/trace-context.js";
+import {
+  metricsCollector,
+  MetricsCollector,
+} from "../execution-trace/metrics-collector.js";
+
+export { traceContext, TraceContext, metricsCollector, MetricsCollector };
+
+/**
+ * 初始化可观测性模块
+ * @param {Object} [options={}]
+ * @param {boolean} [options.tracingEnabled=true] - 是否启用追踪
+ * @param {boolean} [options.metricsEnabled=true] - 是否启用指标收集
+ */
+export function initObservability(options = {}) {
+  const { tracingEnabled = true, metricsEnabled = true } = options;
+
+  // 可观测性模块初始化逻辑
+  return {
+    tracingEnabled,
+    metricsEnabled,
+    traceContext,
+    metricsCollector,
+  };
+}
+
+export * from "../execution-trace/index.js";

package/src/lib/observability/otlp-exporter.js

@@ -0,0 +1,260 @@
+/**
+ * OTLP Exporter — M8 Observability
+ * OpenTelemetry Protocol exporter for spans and metrics
+ * Sends to localhost:4318 by default, with batching and retry
+ */
+
+import http from "node:http";
+import https from "node:https";
+import { URL } from "node:url";
+
+class OtlpExporter {
+  constructor(options = {}) {
+    this.endpoint =
+      options.endpoint ||
+      process.env.OTEL_EXPORTER_OTLP_ENDPOINT ||
+      "http://localhost:4318";
+    this.headers = options.headers || {};
+    this.serviceName =
+      options.serviceName ||
+      process.env.OTEL_SERVICE_NAME ||
+      "chainlesschain-cli";
+    this.batchSize = options.batchSize || 512;
+    this.flushIntervalMs = options.flushIntervalMs || 5000;
+    this._spanBuffer = [];
+    this._metricBuffer = [];
+    this._timer = null;
+    this._droppedSpans = 0;
+    this._droppedMetrics = 0;
+    this._failedExports = 0;
+    this._successfulExports = 0;
+    this._enabled = options.enabled !== false;
+    if (this._enabled) {
+      this._startFlushTimer();
+    }
+  }
+
+  _startFlushTimer() {
+    if (this._timer) clearInterval(this._timer);
+    this._timer = setInterval(() => this.flush(), this.flushIntervalMs);
+    this._timer.unref?.();
+  }
+
+  _getHttpModule(urlStr) {
+    return urlStr.startsWith("https:") ? https : http;
+  }
+
+  _post(path, data, contentType) {
+    if (!this._enabled) return Promise.resolve();
+    return new Promise((resolve) => {
+      try {
+        const url = new URL(path, this.endpoint);
+        const mod = this._getHttpModule(url.protocol);
+        const payload = JSON.stringify(data);
+        const req = mod.request(
+          {
+            hostname: url.hostname,
+            port: url.port,
+            path: url.pathname + url.search,
+            method: "POST",
+            headers: {
+              "Content-Type": contentType,
+              "Content-Length": Buffer.byteLength(payload),
+              ...this.headers,
+            },
+            timeout: 10000,
+          },
+          (res) => {
+            res.resume();
+            if (res.statusCode >= 200 && res.statusCode < 300) {
+              this._successfulExports++;
+            } else {
+              this._failedExports++;
+            }
+            resolve();
+          },
+        );
+        req.on("error", () => {
+          this._failedExports++;
+          resolve();
+        });
+        req.on("timeout", () => {
+          req.destroy();
+          this._failedExports++;
+          resolve();
+        });
+        req.write(payload);
+        req.end();
+      } catch {
+        resolve();
+      }
+    });
+  }
+
+  exportSpans(spans) {
+    if (!this._enabled) return;
+    for (const span of spans) {
+      if (this._spanBuffer.length >= this.batchSize) {
+        this._spanBuffer.shift();
+        this._droppedSpans++;
+      }
+      this._spanBuffer.push({
+        resourceSpans: [
+          {
+            resource: {
+              attributes: [
+                {
+                  key: "service.name",
+                  value: { stringValue: this.serviceName },
+                },
+              ],
+            },
+            scopeSpans: [
+              {
+                scope: { name: span.component || "chainlesschain" },
+                spans: [this._toOtlpSpan(span)],
+              },
+            ],
+          },
+        ],
+      });
+    }
+  }
+
+  _toOtlpSpan(span) {
+    return {
+      traceId: span.traceId || "",
+      spanId: span.spanId || "",
+      parentSpanId: span.parentSpanId || "",
+      name: span.name || "unknown",
+      kind: this._toSpanKind(span.kind),
+      startTimeUnixNano: (span.startTime || Date.now()) * 1_000_000,
+      endTimeUnixNano: (span.endTime || Date.now()) * 1_000_000,
+      attributes: Object.entries(span.attributes || {}).map(([k, v]) => ({
+        key: k,
+        value: this._toAttrValue(v),
+      })),
+      status: { code: span.error ? 2 : 1, message: span.error?.message || "" },
+      events: (span.events || []).map((e) => ({
+        timeUnixNano: (e.time || Date.now()) * 1_000_000,
+        name: e.name,
+        attributes: Object.entries(e.attributes || {}).map(([k, v]) => ({
+          key: k,
+          value: this._toAttrValue(v),
+        })),
+      })),
+    };
+  }
+
+  _toSpanKind(kind) {
+    const map = { internal: 0, server: 1, client: 2, producer: 3, consumer: 4 };
+    return map[kind] ?? 0;
+  }
+
+  _toAttrValue(v) {
+    if (typeof v === "string") return { stringValue: v };
+    if (typeof v === "number")
+      return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+    if (typeof v === "boolean") return { boolValue: v };
+    return { stringValue: String(v) };
+  }
+
+  exportMetrics(metrics) {
+    if (!this._enabled) return;
+    for (const metric of metrics) {
+      if (this._metricBuffer.length >= this.batchSize) {
+        this._metricBuffer.shift();
+        this._droppedMetrics++;
+      }
+      this._metricBuffer.push({
+        resourceMetrics: [
+          {
+            resource: {
+              attributes: [
+                {
+                  key: "service.name",
+                  value: { stringValue: this.serviceName },
+                },
+              ],
+            },
+            scopeMetrics: [
+              {
+                scope: { name: metric.component || "chainlesschain" },
+                metrics: [this._toOtlpMetric(metric)],
+              },
+            ],
+          },
+        ],
+      });
+    }
+  }
+
+  _toOtlpMetric(metric) {
+    return {
+      name: metric.name,
+      description: metric.description || "",
+      unit: metric.unit || "1",
+      [metric.type === "histogram"
+        ? "histogram"
+        : metric.type === "sum"
+          ? "sum"
+          : "gauge"]: {
+        dataPoints: [
+          {
+            attributes: Object.entries(metric.attributes || {}).map(
+              ([k, v]) => ({ key: k, value: this._toAttrValue(v) }),
+            ),
+            timeUnixNano: Date.now() * 1_000_000,
+            ...(metric.type === "histogram"
+              ? {
+                  count: metric.value?.count || 0,
+                  sum: metric.value?.sum || 0,
+                  bucketCounts: metric.value?.bucketCounts || [],
+                  explicitBounds: metric.value?.explicitBounds || [],
+                }
+              : { asDouble: metric.value || 0 }),
+          },
+        ],
+        aggregationTemporality: 1,
+        isMonotonic: metric.type === "sum",
+      },
+    };
+  }
+
+  async flush() {
+    if (!this._enabled) return;
+    const spans = this._spanBuffer.splice(0);
+    const metrics = this._metricBuffer.splice(0);
+    const promises = [];
+    for (const span of spans)
+      promises.push(this._post("/v1/traces", span, "application/json"));
+    for (const metric of metrics)
+      promises.push(this._post("/v1/metrics", metric, "application/json"));
+    await Promise.allSettled(promises);
+  }
+
+  shutdown() {
+    if (this._timer) clearInterval(this._timer);
+    return this.flush();
+  }
+
+  getStats() {
+    return {
+      enabled: this._enabled,
+      bufferedSpans: this._spanBuffer.length,
+      bufferedMetrics: this._metricBuffer.length,
+      droppedSpans: this._droppedSpans,
+      droppedMetrics: this._droppedMetrics,
+      failedExports: this._failedExports,
+      successfulExports: this._successfulExports,
+    };
+  }
+}
+
+let _defaultExporter = null;
+export function getDefaultOtlpExporter() {
+  if (!_defaultExporter) _defaultExporter = new OtlpExporter();
+  return _defaultExporter;
+}
+export { OtlpExporter };
+export default OtlpExporter;

package/src/lib/otlp-exporter.js

@@ -0,0 +1,45 @@
+/**
+ * OTLP Exporter - Minimal OTLP/HTTP trace exporter for M6 observability
+ * Strictly bounded to observability layer only, no cross-layer calls
+ */
+export class OTLPTraceExporter {
+  constructor(options = {}) {
+    this.endpoint = options.endpoint || "http://localhost:4318/v1/traces";
+    this._queue = [];
+  }
+
+  export(span) {
+    const payload = {
+      resourceSpans: [{
+        resource: { attributes: [{ key: "service.name", value: { stringValue: "cc-cli" } }] },
+        scopeSpans: [{
+          spans: [{
+            traceId: span.traceId,
+            spanId: span.spanId,
+            name: span.name || "span",
+            kind: 1,
+            startTimeUnixNano: span.startTime ? BigInt(span.startTime * 1e6).toString() : BigInt(Date.now() * 1e6).toString(),
+            endTimeUnixNano: span.endTime ? BigInt(span.endTime * 1e6).toString() : undefined,
+            attributes: (span.metadata ? Object.entries(span.metadata).map(([k, v]) => ({ key: k, value: { stringValue: String(v) } })) : []),
+          }]
+        }]
+      }]
+    };
+    // Fire and forget, no blocking
+    fetch(this.endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    }).catch(() => {});
+    return true;
+  }
+}
+
+let defaultExporter = null;
+export function initOTLPExporter(endpoint) {
+  if (!defaultExporter && endpoint) {
+    defaultExporter = new OTLPTraceExporter({ endpoint: endpoint.endsWith("/v1/traces") ? endpoint : endpoint.replace(/\/?$/, "/v1/traces") });
+    globalThis.ccRuntime?.traceContext.onEnd((span) => defaultExporter.export(span));
+  }
+  return defaultExporter;
+}

package/src/lib/process-execution-broker/SPAWN_AUDIT_REPORT.md

@@ -0,0 +1,117 @@
+# Process Execution Broker - Spawn/Exec Call Site Audit Report
+
+> Audit Date: 2026-07-18
+> Auditor: Agent
+> Scope: `packages/cli/src`
+
+## Executive Summary
+
+Total direct `child_process` call sites identified: **~85+**
+- `spawn`: ~40 call sites
+- `spawnSync`: ~25 call sites
+- `execSync`: ~15 call sites
+- `execFileSync`: ~8 call sites
+- `execFile`: ~2 call sites
+- `fork`: ~1 call site
+
+## Classification by Risk Category
+
+### A. Agent Self-Spawn (HIGH PRIORITY - must route through Broker)
+These are the primary surfaces where the agent spawns sub-agents or child cc processes:
+
+| File | Function | Type | Purpose |
+|------|----------|------|---------|
+| `commands/agenda.js` | `defaultSpawnAgent()` | spawn | Wakeup/cron scheduled agent execution |
+| `commands/background-session.js` | - | spawn | Background session agent |
+| `commands/batch.js` | `spawnAgent()` | spawn + execFileSync | Batch agent execution |
+| `commands/eval.js` | - | spawn + spawnSync | Eval child processes |
+| `commands/loop.js` | `spawnIteration()` | spawn | Loop mode iteration self-spawn |
+| `commands/routine.js` | - | spawn + execFile | Routine execution |
+| `commands/team.js` | `spawnAgent()` | spawn | Team/cowork multi-agent |
+| `gateways/ws/ws-server.js` | - | spawn | WebSocket gateway spawned CLI commands |
+| `harness/background-task-manager.js` | - | fork | Background task forked workers |
+| `lib/background-agent-supervisor.js` | - | spawn + spawnSync | Background agent supervision |
+| `lib/agent-team/team-worktree.js` | - | spawn + execFileSync | Team worktree agent |
+| `lib/claude-code-bridge.js` | - | spawn + execSync | Claude Code bridge execution |
+| `lib/agent-sandbox.js` | - | spawnSync | Sandbox (docker/bwrap) execution |
+
+### B. MCP Server Process (MEDIUM PRIORITY)
+| File | Function | Type | Purpose |
+|------|----------|------|---------|
+| `harness/mcp-client.js` | - | spawn | MCP stdio server processes |
+| `lib/lsp/lsp-client.js` | - | spawn | LSP server processes |
+
+### C. Git Operations (SAFE - can keep direct)
+| File | Type | Count |
+|------|------|-------|
+| `commands/review.js` | spawnSync | 2 |
+| `commands/session.js` | execFileSync | 1 |
+| `harness/worktree-isolator.js` | execSync | 3 |
+| `lib/agent-worktree.js` | execFileSync/execSync | multiple |
+| `lib/checkpoint-store.js` | spawnSync | multiple |
+| `lib/cloud/bundle.js` | execFileSync | multiple |
+| `lib/git-integration.js` | execSync/spawnSync | multiple |
+
+### D. Package/System Management (SAFE - can keep direct)
+| File | Type | Purpose |
+|------|------|---------|
+| `auth/npm-auth.js` | execSync | npm login/whoami |
+| `commands/config.js` | execSync | Open editor |
+| `commands/init.js` | execSync/spawnSync | Init tool probing |
+| `commands/memory.js` | execSync | Open editor |
+| `commands/update.js` | execSync | npm install -g |
+| `lib/api-key-helper.js` | execSync | Credential helper |
+| `lib/chrome-connector.js` | spawn | Chrome debugger |
+| `lib/doctor-checkup.js` | execSync/spawnSync | Doctor checks |
+| `lib/downloader.js` | execFileSync | Binary downloads |
+| `lib/ensure-utf8.js` | execSync | Windows codepage |
+| `lib/host-adb-bridge.js` | execFile | ADB bridge |
+
+### E. Hook Execution (BROKER-AWARE already)
+| File | Type | Purpose |
+|------|------|---------|
+| `lib/async-hook-supervisor.cjs` | spawn/spawnSync | Async hooks |
+| `lib/hook-manager.js` | execSync | Legacy hook manager |
+| `lib/hook-runner.cjs` | spawn/spawnSync | Hook runner |
+
+### F. Evaluation/Benchmark (TEST only)
+| File | Type | Purpose |
+|------|------|---------|
+| `lib/eval/tasks.js` | execFileSync | Eval task fixtures |
+| `lib/lsp/benchmark.js` | execFileSync | LSP benchmarks |
+| `lib/computer-use/control-backend.js` | spawnSync | Computer use |
+
+### G. Execution Backend
+| File | Type | Purpose |
+|------|------|---------|
+| `lib/execution-backend.js` | execSync | Shell/Docker/SSH backend |
+
+### H. Background Task Worker
+| File | Type | Purpose |
+|------|------|---------|
+| `harness/background-task-worker.js` | execSync | Worker task execution |
+
+## Migration Plan
+
+### Phase 1 (M1 Deliverable)
+Create ProcessExecutionBroker with core interface, then migrate:
+1. Category A (Agent Self-Spawn) - all HIGH priority sites
+2. Instrument with audit events + logging
+
+### Phase 2 (Post-M1)
+1. Category B (MCP/LSP) - register server processes as supervised children
+2. Keep Categories C/D as `bypassBroker: true` approved calls (with explicit allowlist)
+
+### Phase 3 (M3 deliverable)
+3. Route Category E hooks through Broker for unified supervision
+
+## Bypass Allowlist (Initial)
+The following patterns will be initially marked as `bypassBroker: true` with reason:
+- All `git` command executions (known safe, no agent control over args)
+- Editor opening (`$EDITOR`, `vim`, `nano`, etc.)
+- Package manager operations (`npm`, `pip`)
+- Chrome/ADB debug bridge connections
+- Doctor/diagnostic probes
+- Windows codepage setup (`chcp`)
+- File downloads/extraction (unzip)
+- Test fixtures and benchmarks (test-only code)