chainlesschain 0.162.170 → 0.162.172

package/src/lib/execution-trace/trace-context.js

@@ -0,0 +1,182 @@
+/**
+ * TraceContext - W3C Trace Context 兼容的分布式追踪上下文
+ *
+ * 支持：
+ * - traceparent 头格式: {version}-{traceId}-{parentId}-{traceFlags}
+ * - tracestate 头传播
+ * - AsyncLocalStorage 上下文传播
+ * - Span 创建与管理
+ * - Baggage 透传
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+
+class TraceContext {
+  constructor() {
+    this._asyncLocalStorage = new AsyncLocalStorage();
+    this._spans = new Map();
+    this._listeners = new Set();
+  }
+
+  generateTraceId() {
+    return randomBytes(16).toString("hex");
+  }
+
+  generateSpanId() {
+    return randomBytes(8).toString("hex");
+  }
+
+  parseTraceparent(traceparent) {
+    if (!traceparent) return null;
+    const parts = traceparent.split("-");
+    if (parts.length !== 4) return null;
+    const [version, traceId, parentId, traceFlags] = parts;
+    if (
+      version.length !== 2 ||
+      traceId.length !== 32 ||
+      parentId.length !== 16 ||
+      traceFlags.length !== 2
+    ) {
+      return null;
+    }
+    return { version, traceId, parentId, traceFlags: parseInt(traceFlags, 16) };
+  }
+
+  formatTraceparent(traceId, spanId, traceFlags = 0x01) {
+    return `00-${traceId}-${spanId}-${traceFlags.toString(16).padStart(2, "0")}`;
+  }
+
+  getCurrentContext() {
+    return this._asyncLocalStorage.getStore();
+  }
+
+  startRootSpan(name, attributes = {}) {
+    const traceId = this.generateTraceId();
+    const spanId = this.generateSpanId();
+    const context = {
+      traceId,
+      spanId,
+      parentSpanId: null,
+      name,
+      attributes,
+      startTime: Date.now(),
+      tracestate: "",
+      baggage: {},
+    };
+    this._spans.set(spanId, context);
+    this._emit("span:start", context);
+    return context;
+  }
+
+  startSpan(name, attributes = {}) {
+    const parent = this.getCurrentContext();
+    if (!parent) {
+      return this.startRootSpan(name, attributes);
+    }
+    const spanId = this.generateSpanId();
+    const context = {
+      traceId: parent.traceId,
+      spanId,
+      parentSpanId: parent.spanId,
+      name,
+      attributes: { ...attributes },
+      startTime: Date.now(),
+      tracestate: parent.tracestate || "",
+      baggage: { ...(parent.baggage || {}) },
+    };
+    this._spans.set(spanId, context);
+    this._emit("span:start", context);
+    return context;
+  }
+
+  endSpan(span, status = { code: "OK" }) {
+    if (!span || !this._spans.has(span.spanId)) return;
+    span.endTime = Date.now();
+    span.duration = span.endTime - span.startTime;
+    span.status = status;
+    this._emit("span:end", span);
+    this._spans.delete(span.spanId);
+  }
+
+  async runInContext(context, fn) {
+    return this._asyncLocalStorage.run(context, fn);
+  }
+
+  getPropagationEnv() {
+    const ctx = this.getCurrentContext();
+    if (!ctx) return {};
+    const env = {
+      TRACEPARENT: this.formatTraceparent(ctx.traceId, ctx.spanId),
+    };
+    if (ctx.tracestate) {
+      env.TRACESTATE = ctx.tracestate;
+    }
+    if (ctx.baggage && Object.keys(ctx.baggage).length > 0) {
+      env.BAGGAGE = Object.entries(ctx.baggage)
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+        .join(",");
+    }
+    return env;
+  }
+
+  extractFromEnv(env = process.env) {
+    const traceparent = env.TRACEPARENT || env.traceparent;
+    if (!traceparent) return null;
+    const parsed = this.parseTraceparent(traceparent);
+    if (!parsed) return null;
+    const context = {
+      traceId: parsed.traceId,
+      spanId: parsed.parentId,
+      parentSpanId: null,
+      name: "inherited",
+      attributes: {},
+      startTime: Date.now(),
+      tracestate: env.TRACESTATE || env.tracestate || "",
+      baggage: this._parseBaggage(env.BAGGAGE || env.baggage),
+    };
+    return context;
+  }
+
+  on(event, listener) {
+    this._listeners.add({ event, listener });
+  }
+
+  off(event, listener) {
+    for (const entry of this._listeners) {
+      if (entry.event === event && entry.listener === listener) {
+        this._listeners.delete(entry);
+        break;
+      }
+    }
+  }
+
+  _emit(event, data) {
+    for (const { event: ev, listener } of this._listeners) {
+      if (ev === event) {
+        try {
+          listener(data);
+        } catch (e) {
+          // Silently ignore listener errors
+        }
+      }
+    }
+  }
+
+  _parseBaggage(baggage) {
+    if (!baggage) return {};
+    const result = {};
+    for (const pair of baggage.split(",")) {
+      const eqIdx = pair.indexOf("=");
+      if (eqIdx === -1) continue;
+      const key = decodeURIComponent(pair.slice(0, eqIdx).trim());
+      const value = decodeURIComponent(pair.slice(eqIdx + 1).trim());
+      result[key] = value;
+    }
+    return result;
+  }
+}
+
+export { TraceContext };
+export const traceContext = new TraceContext();
+export default traceContext;

package/src/lib/hook-manager.js

@@ -5,6 +5,7 @@
 
 import crypto from "crypto";
 import { execSync } from "child_process";
+import broker from "./process-execution-broker/index.js";
 
 /**
  * Hook priority levels — lower values run first.
@@ -62,6 +63,13 @@ export const HookEvents = {
   CIFailure: "CIFailure",
   IterationWarning: "IterationWarning",
   IterationBudgetExhausted: "IterationBudgetExhausted",
+  /**
+   * Stop: Fired at the END of every agent turn/loop iteration, BEFORE waiting
+   * for the next user input. Aligns with Claude Code hook spec.
+   * Fires regardless of outcome (success, error, max-iterations, stop).
+   * Does NOT fire on final process exit (use SessionEnd/Shutdown for that).
+   */
+  Stop: "Stop",
 };
 
 /**
@@ -282,6 +290,15 @@ export async function executeHook(hook, context = {}) {
         HOOK_EVENT: hook.event,
         HOOK_CONTEXT: JSON.stringify(context),
       };
+      // M1: Record hook command execution in broker audit log
+      broker.auditLog.push({
+        pid: process.pid,
+        origin: "hook",
+        command: cmd,
+        args: [],
+        startedAt: Date.now(),
+        sessionId: context?.sessionId,
+      });
       const output = execSync(cmd, {
         encoding: "utf-8",
         timeout: hook.timeout || 5000,

package/src/lib/hooks-v2-runtime.js

@@ -0,0 +1,278 @@
+/**
+ * Hooks v2 System — M3-1: 完整18事件schema + 5种executor类型
+ * 对应文档 §2.3
+ *
+ * 支持的18种生命周期事件:
+ *   Session: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
+ *   Auth: PreCommit, PostCommit
+ *   Skill: UserPromptSubmit, SessionStart, SessionEnd
+ *   Model: PreCompact, ModelSelection
+ *   Config: ConfigChange, PermissionAllow, PermissionDeny
+ *   Timeline: TimelineEntry
+ *   MCP: McpRequest, McpResponse
+ *
+ * 支持的executor类型:
+ *   1. command (shell command, current hooks.json only supports this)
+ *   2. http (webhook)
+ *   3. prompt (inline prompt template)
+ *   4. agent (dispatch to cc agent/skill)
+ *   5. js (inline JS function via vm sandbox)
+ */
+
+import { EventEmitter } from "node:events";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import broker from "./process-execution-broker/index.js";
+
+const VALID_HOOK_EVENTS = new Set([
+  // Session
+  "PreToolUse", "PostToolUse", "Notification", "Stop", "SubagentStop",
+  // Auth
+  "PreCommit", "PostCommit",
+  // Skill
+  "UserPromptSubmit", "SessionStart", "SessionEnd",
+  // Model
+  "PreCompact", "ModelSelection",
+  // Config
+  "ConfigChange", "PermissionAllow", "PermissionDeny",
+  // Timeline
+  "TimelineEntry",
+  // MCP
+  "McpRequest", "McpResponse",
+]);
+
+const VALID_EXECUTOR_TYPES = new Set(["command", "http", "prompt", "agent", "js"]);
+
+class HooksV2Runtime extends EventEmitter {
+  constructor(configDir) {
+    super();
+    this.configDir = configDir;
+    this.hooks = new Map(); // eventName -> HookDefinition[]
+    this.executionLog = [];
+    this._loaded = false;
+  }
+
+  /**
+   * @typedef {Object} HookDefinition
+   * @property {string} id
+   * @property {string} event
+   * @property {'command'|'http'|'prompt'|'agent'|'js'} type
+   * @property {string} [command] - for type=command
+   * @property {string[]} [args]
+   * @property {string} [url] - for type=http
+   * @property {string} [method] - GET/POST
+   * @property {Object} [headers]
+   * @property {string} [template] - for type=prompt
+   * @property {string} [agentName] - for type=agent
+   * @property {string} [skillName] - for type=agent
+   * @property {string} [code] - for type=js
+   * @property {number} [timeoutMs]
+   * @property {boolean} [blocking] - default false
+   * @property {string[]} [if] - conditional matchers
+   * @property {string} [description]
+   */
+
+  async loadHooks(hooksPath) {
+    try {
+      const content = await fs.readFile(hooksPath, "utf8");
+      const config = JSON.parse(content);
+      this.hooks.clear();
+
+      const hookDefs = Array.isArray(config) ? config : (config.hooks || []);
+      for (const def of hookDefs) {
+        if (!VALID_HOOK_EVENTS.has(def.event)) {
+          process.emitWarning(`[hooks-v2] Unknown event type: ${def.event}, skipping`);
+          continue;
+        }
+        if (!VALID_EXECUTOR_TYPES.has(def.type)) {
+          process.emitWarning(`[hooks-v2] Unknown executor type: ${def.type} for ${def.event}, skipping`);
+          continue;
+        }
+        const id = def.id || crypto.randomUUID();
+        if (!this.hooks.has(def.event)) this.hooks.set(def.event, []);
+        this.hooks.get(def.event).push({ id, ...def });
+      }
+      this._loaded = true;
+      this.emit("loaded", { count: hookDefs.length, events: Array.from(this.hooks.keys()) });
+    } catch (e) {
+      if (e.code !== "ENOENT") {
+        this.emit("load:error", e);
+      }
+    }
+  }
+
+  /**
+   * Register a hook programmatically
+   */
+  registerHook(def) {
+    if (!VALID_HOOK_EVENTS.has(def.event)) throw new Error(`Invalid event: ${def.event}`);
+    if (!VALID_EXECUTOR_TYPES.has(def.type)) throw new Error(`Invalid executor type: ${def.type}`);
+    const id = def.id || crypto.randomUUID();
+    const full = { id, blocking: false, timeoutMs: 30000, ...def };
+    if (!this.hooks.has(def.event)) this.hooks.set(def.event, []);
+    this.hooks.get(def.event).push(full);
+    return id;
+  }
+
+  unregisterHook(id) {
+    for (const [event, hooks] of this.hooks.entries()) {
+      const idx = hooks.findIndex(h => h.id === id);
+      if (idx >= 0) {
+        hooks.splice(idx, 1);
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Fire an event - executes all registered hooks
+   * @param {string} eventName
+   * @param {Object} context - event context (tool_name, tool_input, session_id, etc.)
+   * @returns {Promise<{results: Array, blocked: boolean, blockingResult?: any}>}
+   */
+  async emitEvent(eventName, context = {}) {
+    if (!VALID_HOOK_EVENTS.has(eventName)) {
+      throw new Error(`Invalid hook event: ${eventName}`);
+    }
+
+    const hooks = this.hooks.get(eventName) || [];
+    const results = [];
+    let blocked = false;
+    let blockingResult = null;
+
+    for (const hook of hooks) {
+      const execId = crypto.randomUUID();
+      const start = Date.now();
+      const record = { execId, hookId: hook.id, event: eventName, type: hook.type, startedAt: new Date() };
+
+      try {
+        let result;
+        switch (hook.type) {
+          case "command":
+            result = await this._execCommand(hook, context);
+            break;
+          case "http":
+            result = await this._execHttp(hook, context);
+            break;
+          case "prompt":
+            result = await this._execPrompt(hook, context);
+            break;
+          case "agent":
+            result = await this._execAgent(hook, context);
+            break;
+          case "js":
+            result = await this._execJs(hook, context);
+            break;
+        }
+
+        record.durationMs = Date.now() - start;
+        record.status = "success";
+        record.result = result;
+        results.push(record);
+
+        // Check for blocking decision
+        if (hook.blocking && result && result.decision === "block") {
+          blocked = true;
+          blockingResult = result;
+          record.blocked = true;
+        }
+
+        this.emit("hook:success", record);
+      } catch (err) {
+        record.durationMs = Date.now() - start;
+        record.status = "error";
+        record.error = err.message;
+        results.push(record);
+        this.emit("hook:error", record);
+      }
+
+      this.executionLog.push(record);
+    }
+
+    return { results, blocked, blockingResult };
+  }
+
+  async _execCommand(hook, context) {
+    const child = await broker.spawn(
+      hook.command, hook.args || [],
+      {
+        env: { ...process.env, CC_HOOK_EVENT: hook.event, CC_HOOK_CONTEXT: JSON.stringify(context) },
+        stdio: "pipe",
+        timeout: hook.timeoutMs,
+      },
+      { origin: "hook", hookName: hook.id, timeout: hook.timeoutMs },
+    );
+    return new Promise((resolve, reject) => {
+      let stdout = "", stderr = "";
+      child.stdout.on("data", d => stdout += d);
+      child.stderr.on("data", d => stderr += d);
+      child.on("exit", (code) => {
+        if (code === 0) {
+          let parsed = {};
+          try { parsed = JSON.parse(stdout); } catch { parsed = { raw: stdout }; }
+          resolve({ ...parsed, exitCode: code, stderr });
+        } else {
+          reject(new Error(`Hook command failed with exit ${code}: ${stderr}`));
+        }
+      });
+    });
+  }
+
+  async _execHttp(hook, context) {
+    // Simple HTTP webhook executor
+    const method = hook.method || "POST";
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), hook.timeoutMs || 30000);
+    try {
+      const res = await fetch(hook.url, {
+        method,
+        headers: { "Content-Type": "application/json", ...(hook.headers || {}) },
+        body: method !== "GET" ? JSON.stringify({ event: hook.event, context }) : undefined,
+        signal: controller.signal,
+      });
+      clearTimeout(timer);
+      return { status: res.status, body: await res.text().catch(() => "") };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async _execPrompt(hook, context) {
+    // Prompt template execution - returns expanded prompt for agent prepend
+    const vars = { ...context };
+    let expanded = hook.template || "";
+    expanded = expanded.replace(/\$\{(\w+)\}/g, (_, k) => vars[k] ?? "");
+    return { decision: "augment", prompt: expanded };
+  }
+
+  async _execAgent(hook, context) {
+    // Dispatch to agent/skill - stub for full integration
+    return { decision: "delegate", agentName: hook.agentName, skillName: hook.skillName, context };
+  }
+
+  async _execJs(hook, context) {
+    // In-process JS execution via vm (sandboxed) - stub for full vm2/isolated-vm integration
+    return { decision: "noop", note: "JS executor stub - context received", contextKeys: Object.keys(context) };
+  }
+
+  /** Get all registered hooks */
+  getHookRegistry() {
+    const registry = {};
+    for (const [event, hooks] of this.hooks.entries()) {
+      registry[event] = hooks.map(h => ({ id: h.id, type: h.type, description: h.description, blocking: h.blocking }));
+    }
+    return registry;
+  }
+
+  /** Get recent execution log */
+  getExecutionLog(limit = 50) {
+    return this.executionLog.slice(-limit);
+  }
+}
+
+// Singleton instance
+const hooksRuntime = new HooksV2Runtime();
+export default hooksRuntime;
+export { HooksV2Runtime, VALID_HOOK_EVENTS, VALID_EXECUTOR_TYPES };

package/src/lib/interaction-adapter.js

@@ -187,7 +187,7 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     });
   }
 
-  _ask(questionType, question, extra = {}) {
+  _ask(questionType, question, extra = {}, options = {}) {
     return this._request(
       {
         type: "question",
@@ -195,7 +195,12 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
         question,
         ...extra,
       },
-      { kind: "question" },
+      {
+        kind: "question",
+        // Approval binding pass-through: a permission-gate producer supplies
+        // it; plain questions never carry one (message stays byte-identical).
+        ...(options.binding ? { binding: options.binding } : {}),
+      },
     );
   }
 
@@ -207,10 +212,26 @@ export class WebSocketInteractionAdapter extends InteractionAdapter {
     return this._ask("select", question, { choices });
   }
 
+  /**
+   * @param {string} question
+   * @param {boolean|object} [defaultVal] — boolean (legacy, byte-identical) or
+   *   an options object `{ default, binding, ...extra }`: `binding` rides out
+   *   on the request so the client must echo it back on approve (verified in
+   *   _resolvePending, mismatched approve → deny); any other keys merge into
+   *   the question message (e.g. structured `approval` context for UIs).
+   */
   async askConfirm(question, defaultVal = true) {
-    const answer = await this._ask("confirm", question, {
-      default: defaultVal,
-    });
+    const opts =
+      defaultVal !== null && typeof defaultVal === "object"
+        ? defaultVal
+        : { default: defaultVal };
+    const { binding = null, default: dflt = true, ...extra } = opts;
+    const answer = await this._ask(
+      "confirm",
+      question,
+      { default: dflt, ...extra },
+      binding ? { binding } : {},
+    );
     // Normalize to boolean
     if (typeof answer === "boolean") return answer;
     return answer === "true" || answer === "yes" || answer === "y";

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,33 @@
+/**
+ * Observability - 可观测性模块统一导出
+ * M3 阶段模块：包含分布式追踪 + 性能指标收集
+ */
+
+export {
+  traceContext,
+  TraceContext,
+} from "../execution-trace/trace-context.js";
+export {
+  metricsCollector,
+  MetricsCollector,
+} from "../execution-trace/metrics-collector.js";
+
+/**
+ * 初始化可观测性模块
+ * @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";