@ap3x/observe 0.1.0

package/dist/index.js

@@ -0,0 +1,913 @@
+// src/envelope.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { uuidv7 } from "@ap3x/agent-core";
+var contextStorage = new AsyncLocalStorage();
+function newTraceContext() {
+  return { traceId: uuidv7(), spanId: uuidv7() };
+}
+function childContext(parent) {
+  const base = parent ?? contextStorage.getStore();
+  if (!base) return newTraceContext();
+  return { traceId: base.traceId, spanId: uuidv7(), parentSpanId: base.spanId };
+}
+function currentTraceContext() {
+  return contextStorage.getStore();
+}
+function runInTrace(ctx, fn) {
+  return contextStorage.run(ctx, fn);
+}
+function withSpan(fn) {
+  return contextStorage.run(childContext(), fn);
+}
+
+// src/pipeline.ts
+var MAX_TRACKED_TRACES = 1e4;
+var TracePipeline = class {
+  #sinks;
+  #seqByTrace = /* @__PURE__ */ new Map();
+  #dropped = 0;
+  #now;
+  #root;
+  constructor(options) {
+    this.#sinks = new Set(options?.sinks ?? []);
+    this.#now = options?.now ?? Date.now;
+  }
+  get fallbackRoot() {
+    this.#root ??= newTraceContext();
+    return this.#root;
+  }
+  get dropped() {
+    return this.#dropped;
+  }
+  /** Forget a finished trace's seq counter (footer written, run over). */
+  releaseTrace(traceId) {
+    this.#seqByTrace.delete(traceId);
+  }
+  addSink(sink) {
+    this.#sinks.add(sink);
+    return () => this.#sinks.delete(sink);
+  }
+  emit(input, ctx) {
+    const context = ctx ?? currentTraceContext() ?? this.fallbackRoot;
+    const seq = (this.#seqByTrace.get(context.traceId) ?? 0) + 1;
+    this.#seqByTrace.set(context.traceId, seq);
+    if (this.#seqByTrace.size > MAX_TRACKED_TRACES) {
+      const oldest = this.#seqByTrace.keys().next().value;
+      if (oldest !== void 0 && oldest !== context.traceId) this.#seqByTrace.delete(oldest);
+    }
+    const event = {
+      traceId: context.traceId,
+      spanId: context.spanId,
+      ...context.parentSpanId ? { parentSpanId: context.parentSpanId } : {},
+      seq,
+      ts: this.#now(),
+      source: input.source,
+      name: input.name,
+      ...input.agent ? { agent: input.agent } : {},
+      ...input.usage ? { usage: input.usage } : {},
+      ...input.data !== void 0 ? { data: input.data } : {}
+    };
+    for (const sink of this.#sinks) {
+      try {
+        sink.onEvent(event);
+      } catch {
+        this.#dropped += 1;
+      }
+    }
+    return event;
+  }
+};
+
+// src/trace-writer.ts
+import { appendFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var TraceWriter = class {
+  #dir;
+  #now;
+  #open = /* @__PURE__ */ new Map();
+  /** Trace IDs whose header write failed permanently — never retried. */
+  #failed = /* @__PURE__ */ new Set();
+  #dropped = 0;
+  #dirReady = false;
+  constructor(options) {
+    this.#dir = options?.dir ?? join(homedir(), ".ap3x", "traces");
+    this.#now = options?.now ?? Date.now;
+  }
+  /** Aggregate dropped-event count across all traces. */
+  get dropped() {
+    return this.#dropped;
+  }
+  onEvent(event) {
+    const trace = this.#openTrace(event.traceId);
+    if (!trace) return;
+    let line;
+    try {
+      line = JSON.stringify(event);
+    } catch (error) {
+      this.#dropped += 1;
+      trace.dropped += 1;
+      if (!trace.warned) {
+        trace.warned = true;
+        console.error(`trace writer: cannot serialize event for ${trace.file}: ${String(error)}`);
+      }
+      return;
+    }
+    this.#append(trace, line);
+  }
+  close(traceId, outcome) {
+    const trace = this.#open.get(traceId);
+    if (!trace) return;
+    this.#append(
+      trace,
+      JSON.stringify({
+        type: "trace_end",
+        traceId,
+        // Per-trace dropped count, not the writer-global aggregate.
+        dropped: trace.dropped,
+        ...outcome ? { outcome } : {},
+        endedAt: this.#now()
+      })
+    );
+    this.#open.delete(traceId);
+  }
+  closeAll(outcome) {
+    for (const traceId of [...this.#open.keys()]) this.close(traceId, outcome);
+  }
+  #openTrace(traceId) {
+    const existing = this.#open.get(traceId);
+    if (existing) return existing;
+    if (this.#failed.has(traceId)) {
+      this.#dropped += 1;
+      return void 0;
+    }
+    const trace = {
+      file: join(this.#dir, `${traceId}.jsonl`),
+      warned: false,
+      dropped: 0
+    };
+    try {
+      if (!this.#dirReady) {
+        mkdirSync(this.#dir, { recursive: true });
+        this.#dirReady = true;
+      }
+      appendFileSync(
+        trace.file,
+        `${JSON.stringify({ type: "trace", version: 1, traceId, startedAt: this.#now() })}
+`
+      );
+    } catch (error) {
+      this.#dropped += 1;
+      this.#failed.add(traceId);
+      console.error(`trace writer: cannot open ${trace.file}: ${String(error)}`);
+      return void 0;
+    }
+    this.#open.set(traceId, trace);
+    return trace;
+  }
+  #append(trace, line) {
+    try {
+      appendFileSync(trace.file, `${line}
+`);
+    } catch (error) {
+      this.#dropped += 1;
+      trace.dropped += 1;
+      if (!trace.warned) {
+        trace.warned = true;
+        console.error(`trace writer: write failed for ${trace.file}: ${String(error)}`);
+      }
+    }
+  }
+};
+
+// src/trace-file.ts
+function parseTraceFile(content) {
+  const parsed = { events: [], malformedLines: 0 };
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let raw;
+    try {
+      raw = JSON.parse(trimmed);
+    } catch {
+      parsed.malformedLines += 1;
+      continue;
+    }
+    if (typeof raw !== "object" || raw === null) {
+      parsed.malformedLines += 1;
+      continue;
+    }
+    const row = raw;
+    if (row.type === "trace") parsed.header = row;
+    else if (row.type === "trace_end") parsed.footer = row;
+    else if (typeof row.seq === "number" && typeof row.name === "string") {
+      parsed.events.push(row);
+    } else parsed.malformedLines += 1;
+  }
+  return parsed;
+}
+function summarizeTrace(parsed) {
+  const summary = {
+    traceId: parsed.header?.traceId ?? parsed.events[0]?.traceId ?? "unknown",
+    dropped: parsed.footer?.dropped ?? 0,
+    events: parsed.events.length,
+    malformedLines: parsed.malformedLines,
+    turns: 0,
+    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    toolCalls: 0,
+    toolFailures: 0,
+    tools: {},
+    hookRuns: 0,
+    hookErrors: 0,
+    agents: []
+  };
+  if (parsed.header) summary.startedAt = parsed.header.startedAt;
+  if (parsed.footer) summary.endedAt = parsed.footer.endedAt;
+  if (parsed.footer?.outcome !== void 0) summary.outcome = parsed.footer.outcome;
+  const agents = /* @__PURE__ */ new Set();
+  let costTotal;
+  for (const event of parsed.events) {
+    if (event.agent?.name) agents.add(event.agent.name);
+    if (event.name === "turn_end") {
+      summary.turns += 1;
+      if (event.usage) {
+        summary.usage.input += event.usage.input;
+        summary.usage.output += event.usage.output;
+        summary.usage.cacheRead += event.usage.cacheRead;
+        summary.usage.cacheWrite += event.usage.cacheWrite;
+        const total = event.usage.cost?.total;
+        if (typeof total === "number") costTotal = (costTotal ?? 0) + total;
+      }
+    } else if (event.name === "tool_execution_end") {
+      summary.toolCalls += 1;
+      const data = event.data ?? {};
+      const name = data.toolName ?? "unknown";
+      const stats = summary.tools[name] ?? { calls: 0, failures: 0 };
+      stats.calls += 1;
+      if (data.isError === true) {
+        stats.failures += 1;
+        summary.toolFailures += 1;
+      }
+      summary.tools[name] = stats;
+    } else if (event.source === "hook") {
+      if (event.name === "hook_run") summary.hookRuns += 1;
+      else if (event.name === "hook_error") summary.hookErrors += 1;
+    }
+  }
+  summary.agents = [...agents];
+  const end = summary.endedAt ?? parsed.events.at(-1)?.ts;
+  if (summary.startedAt !== void 0 && end !== void 0) {
+    summary.endedAt = end;
+    summary.durationMs = end - summary.startedAt;
+  }
+  if (costTotal !== void 0) summary.usage.costTotal = costTotal;
+  return summary;
+}
+
+// src/queued-sink.ts
+var QueuedSink = class {
+  #inner;
+  #queue = [];
+  #max;
+  #scheduled = false;
+  #dropped = 0;
+  constructor(inner, options) {
+    this.#inner = inner;
+    this.#max = options?.maxQueue ?? 1024;
+  }
+  get dropped() {
+    return this.#dropped;
+  }
+  onEvent(event) {
+    if (this.#queue.length >= this.#max) {
+      this.#dropped += 1;
+      return;
+    }
+    this.#queue.push(event);
+    if (!this.#scheduled) {
+      this.#scheduled = true;
+      setImmediate(() => this.#drain());
+    }
+  }
+  #drain() {
+    this.#scheduled = false;
+    const batch = this.#queue.splice(0);
+    for (const event of batch) {
+      try {
+        this.#inner.onEvent(event);
+      } catch {
+        this.#dropped += 1;
+      }
+    }
+  }
+  /** Drain everything queued right now (shutdown, tests). */
+  flush() {
+    this.#drain();
+  }
+};
+
+// src/taps/agent.ts
+var ARGS_CAP = 4096;
+function truncate(text) {
+  return text.length > ARGS_CAP ? `${text.slice(0, ARGS_CAP)}\u2026[truncated]` : text;
+}
+function safeSerializeArgs(args) {
+  try {
+    return truncate(JSON.stringify(args));
+  } catch {
+    return "[unserializable]";
+  }
+}
+function mapEvent(e) {
+  switch (e.type) {
+    case "agent_start":
+      return { source: "agent", name: "agent_start" };
+    case "agent_end":
+      return { source: "agent", name: "agent_end", data: { messageCount: e.messages.length } };
+    case "turn_start":
+      return { source: "agent", name: "turn_start" };
+    case "turn_end":
+      return {
+        source: "agent",
+        name: "turn_end",
+        usage: e.message.usage,
+        data: { stopReason: e.message.stopReason, toolResults: e.toolResults.length }
+      };
+    case "message_start":
+    case "message_end":
+      return { source: "agent", name: e.type, data: { role: e.message.role } };
+    case "compaction":
+      return {
+        source: "agent",
+        name: "compaction",
+        data: { tokensBefore: e.tokensBefore, summaryChars: e.summary.length }
+      };
+    case "tool_execution_start":
+      return {
+        source: "tool",
+        name: "tool_execution_start",
+        data: {
+          toolCallId: e.toolCallId,
+          toolName: e.toolName,
+          args: safeSerializeArgs(e.args)
+        }
+      };
+    case "tool_execution_end":
+      return {
+        source: "tool",
+        name: "tool_execution_end",
+        data: { toolCallId: e.toolCallId, toolName: e.toolName, isError: e.isError }
+      };
+    default:
+      return void 0;
+  }
+}
+function observeAgent(source, pipeline, options) {
+  const attachCtx = options?.ctx ?? currentTraceContext();
+  return source.subscribe((event) => {
+    try {
+      const input = mapEvent(event);
+      if (!input) return;
+      if (options?.agent) input.agent = options.agent;
+      pipeline.emit(input, options?.ctx ?? currentTraceContext() ?? attachCtx);
+    } catch {
+      try {
+        options?.onDrop?.();
+      } catch {
+      }
+    }
+  });
+}
+
+// src/taps/swarm.ts
+import { onSwarmEvent, setDelegationSpanWrapper } from "@ap3x/swarms";
+function observeSwarms(pipeline, options) {
+  return onSwarmEvent((event) => {
+    try {
+      const agentName = "agentName" in event ? event.agentName : void 0;
+      pipeline.emit({
+        source: "swarm",
+        name: event.type,
+        ...agentName ? { agent: { name: agentName } } : {},
+        data: event
+      });
+    } catch {
+      try {
+        options?.onDrop?.();
+      } catch {
+      }
+    }
+  });
+}
+function enableDelegationSpans() {
+  setDelegationSpanWrapper((fn) => runInTrace(childContext(), fn));
+  return () => setDelegationSpanWrapper(void 0);
+}
+
+// src/hooks/types.ts
+var HOOK_EVENT_NAMES = [
+  "PreToolUse",
+  "PostToolUse",
+  "RunStart",
+  "TurnStart",
+  "Stop",
+  "PreCompact",
+  "SubagentStart",
+  "SubagentStop"
+];
+function defineHook(hook) {
+  return hook;
+}
+
+// src/hooks/engine.ts
+var GATING_EVENTS = /* @__PURE__ */ new Set([
+  "PreToolUse",
+  "SubagentStart",
+  "PreCompact",
+  "Stop"
+]);
+var DEFAULT_GATING_TIMEOUT_MS = 1e4;
+var DEFAULT_HOOK_TIMEOUT_MS = 3e4;
+var HookTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`hook timed out after ${timeoutMs}ms`);
+    this.timeoutMs = timeoutMs;
+    this.name = "HookTimeoutError";
+  }
+  timeoutMs;
+};
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function globMatch(pattern, value) {
+  const rx = new RegExp(`^${pattern.split("*").map(escapeRegExp).join(".*")}$`);
+  return rx.test(value);
+}
+async function withTimeout(fn, ms) {
+  let timer;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(fn),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new HookTimeoutError(ms)), ms);
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+var HookEngine = class {
+  #hooks = [];
+  #pipeline;
+  constructor(options) {
+    this.#pipeline = options?.pipeline;
+  }
+  register(hook) {
+    const stored = hook;
+    this.#hooks.push(stored);
+    return () => {
+      const i = this.#hooks.indexOf(stored);
+      if (i >= 0) this.#hooks.splice(i, 1);
+    };
+  }
+  list() {
+    return this.#hooks;
+  }
+  /** Cheap pre-check so bridges can skip work when nothing listens. */
+  hasHooks(event) {
+    return this.#hooks.some((h) => h.event === event);
+  }
+  async run(event, payload, matchValue) {
+    const decisions = [];
+    for (const [index, hook] of this.#hooks.entries()) {
+      if (hook.event !== event) continue;
+      if (hook.matcher !== void 0 && matchValue !== void 0) {
+        if (!globMatch(hook.matcher, matchValue)) continue;
+      }
+      const timeout = hook.timeout ?? (GATING_EVENTS.has(event) ? DEFAULT_GATING_TIMEOUT_MS : DEFAULT_HOOK_TIMEOUT_MS);
+      const label = hook.name ?? `${event}#${index}`;
+      const startedAt = Date.now();
+      try {
+        const handler = hook.handler;
+        const decision = await withTimeout(() => handler(payload), timeout);
+        this.#pipeline?.emit({
+          source: "hook",
+          name: "hook_run",
+          data: {
+            hook: label,
+            event,
+            durationMs: Date.now() - startedAt,
+            decided: decision !== void 0
+          }
+        });
+        if (decision !== void 0) decisions.push(decision);
+      } catch (error) {
+        const failMode = hook.failMode ?? "open";
+        const message = error instanceof Error ? error.message : String(error);
+        this.#pipeline?.emit({
+          source: "hook",
+          name: "hook_error",
+          data: {
+            hook: label,
+            event,
+            durationMs: Date.now() - startedAt,
+            failMode,
+            error: message
+          }
+        });
+        if (failMode === "closed") {
+          return {
+            decisions,
+            failedClosed: true,
+            failReason: `hook "${label}" failed (failMode closed): ${message}`
+          };
+        }
+      }
+    }
+    return { decisions, failedClosed: false };
+  }
+};
+
+// src/hooks/agent-bridge.ts
+function userMessage(content) {
+  return { role: "user", content, timestamp: Date.now() };
+}
+function createHookAgentHooks(engine) {
+  let firstConsult = true;
+  let turn = 0;
+  return {
+    async getSteeringMessages() {
+      const messages = [];
+      if (firstConsult) {
+        firstConsult = false;
+        const run = await engine.run("RunStart", { turn: 0 });
+        for (const d of run.decisions) if (d.messages) messages.push(...d.messages);
+      }
+      const t = await engine.run("TurnStart", { turn });
+      turn += 1;
+      for (const d of t.decisions) if (d.messages) messages.push(...d.messages);
+      return messages;
+    },
+    async beforeToolCall(toolName, args, toolCallId) {
+      const out = await engine.run("PreToolUse", { toolName, toolCallId, args }, toolName);
+      if (out.failedClosed) {
+        return { block: true, reason: out.failReason ?? "hook failed (failMode closed)" };
+      }
+      let updated;
+      for (const d of out.decisions) {
+        if (d.block) return { block: true, ...d.reason ? { reason: d.reason } : {} };
+        if (d.updatedArgs) updated = { ...updated ?? args, ...d.updatedArgs };
+      }
+      return updated ? { updatedArgs: updated } : void 0;
+    },
+    async afterToolCall(toolName, result, toolCallId, context) {
+      const out = await engine.run(
+        "PostToolUse",
+        {
+          toolName,
+          toolCallId,
+          args: context?.args ?? {},
+          result,
+          isError: result.isError ?? false
+        },
+        toolName
+      );
+      if (out.failedClosed) {
+        return {
+          content: [{ type: "text", text: out.failReason ?? "hook failed (failMode closed)" }],
+          isError: true
+        };
+      }
+      let patch;
+      for (const d of out.decisions) {
+        if (d.override) patch = { ...patch, ...d.override };
+      }
+      return patch;
+    },
+    async getFollowUpMessages() {
+      const out = await engine.run("Stop", { turn });
+      if (!out.failedClosed) {
+        for (const d of out.decisions) {
+          if (d.continue && d.messages?.length) return d.messages;
+        }
+      }
+      firstConsult = true;
+      turn = 0;
+      return [];
+    },
+    async beforeCompaction() {
+      const out = await engine.run("PreCompact", {});
+      if (out.failedClosed) return { defer: true };
+      return out.decisions.some((d) => d.defer) ? { defer: true } : void 0;
+    },
+    reset() {
+      firstConsult = true;
+      turn = 0;
+    }
+  };
+}
+
+// src/hooks/swarm-bridge.ts
+import { onSwarmEvent as onSwarmEvent2, setDelegationGate } from "@ap3x/swarms";
+function attachSwarmHooks(engine) {
+  setDelegationGate(async (request) => {
+    const out = await engine.run(
+      "SubagentStart",
+      {
+        ...request.agentName !== void 0 ? { agentName: request.agentName } : {},
+        mechanism: request.mechanism,
+        depth: request.depth,
+        task: request.task
+      },
+      // "" (not undefined) on purpose: a name matcher expresses "agents named
+      // X", so it never matches an anonymous delegation — hooks that must see
+      // every delegation omit the matcher. (All current emitters pass a name.)
+      request.agentName ?? ""
+    );
+    if (out.failedClosed) {
+      return { block: true, reason: out.failReason ?? "hook failed (failMode closed)" };
+    }
+    for (const d of out.decisions) {
+      if (d.block) return { block: true, ...d.reason ? { reason: d.reason } : {} };
+    }
+    return void 0;
+  });
+  const offEvents = onSwarmEvent2((event) => {
+    if (event.type !== "member_run_end") return;
+    void engine.run(
+      "SubagentStop",
+      {
+        agentName: event.agentName,
+        mechanism: event.mechanism,
+        depth: event.depth,
+        durationMs: event.durationMs,
+        isError: event.isError
+      },
+      event.agentName
+    );
+  });
+  return () => {
+    setDelegationGate(void 0);
+    offEvents();
+  };
+}
+
+// src/hooks/shell.ts
+import { spawn } from "child_process";
+var HookExecutionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HookExecutionError";
+  }
+};
+function runShellHook(command, payloadJson, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = spawn(command, { shell: true, windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill();
+      child.stdout.destroy();
+      child.stderr.destroy();
+      child.stdin.destroy();
+      resolve({ exitCode: null, stdout, stderr, timedOut });
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({ exitCode: null, stdout, stderr: stderr || error.message, timedOut });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ exitCode: code, stdout, stderr, timedOut });
+    });
+    child.stdin.on("error", () => {
+    });
+    child.stdout.on("error", () => {
+    });
+    child.stderr.on("error", () => {
+    });
+    child.stdin.end(payloadJson);
+  });
+}
+function parseStdout(stdout) {
+  const trimmed = stdout.trim();
+  if (!trimmed) return void 0;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(json, key) {
+  const value = json[key];
+  return typeof value === "string" ? value : void 0;
+}
+function boolField(json, key) {
+  return json[key] === true;
+}
+function overrideField(json) {
+  const value = json.override;
+  if (!isPlainObject(value)) return void 0;
+  if ("content" in value) {
+    if (!Array.isArray(value.content)) return void 0;
+    if (!value.content.every((el) => isPlainObject(el) && typeof el.type === "string")) {
+      return void 0;
+    }
+  }
+  return value;
+}
+function shellDecision(event, result) {
+  if (result.timedOut) {
+    throw new HookExecutionError(`shell hook timed out (killed): ${result.stderr.trim()}`.trim());
+  }
+  if (result.exitCode === 2) {
+    const reason = result.stderr.trim() || "blocked by hook";
+    switch (event) {
+      case "PreToolUse":
+      case "SubagentStart":
+        return { block: true, reason };
+      case "PreCompact":
+        return { defer: true };
+      case "Stop":
+        return { continue: true, messages: [userMessage(reason)] };
+      default:
+        throw new HookExecutionError(`shell hook exited 2 at non-gating event ${event}: ${reason}`);
+    }
+  }
+  if (result.exitCode !== 0) {
+    throw new HookExecutionError(
+      `shell hook exited ${result.exitCode ?? "without a code"}: ${result.stderr.trim()}`
+    );
+  }
+  const json = parseStdout(result.stdout);
+  if (!json) return void 0;
+  switch (event) {
+    case "PreToolUse": {
+      const reason = stringField(json, "reason");
+      if (json.decision === "block" || json.updatedArgs) {
+        return {
+          ...json.decision === "block" ? { block: true } : {},
+          ...reason ? { reason } : {},
+          ...json.updatedArgs ? { updatedArgs: json.updatedArgs } : {}
+        };
+      }
+      return void 0;
+    }
+    case "PostToolUse": {
+      const override = overrideField(json);
+      return override ? { override } : void 0;
+    }
+    case "RunStart":
+    case "TurnStart": {
+      const message = stringField(json, "message");
+      return message ? { messages: [userMessage(message)] } : void 0;
+    }
+    case "Stop": {
+      const message = stringField(json, "message");
+      return boolField(json, "continue") && message ? { continue: true, messages: [userMessage(message)] } : void 0;
+    }
+    case "PreCompact":
+      return boolField(json, "defer") ? { defer: true } : void 0;
+    case "SubagentStart": {
+      const reason = stringField(json, "reason");
+      return json.decision === "block" ? { block: true, ...reason ? { reason } : {} } : void 0;
+    }
+    default:
+      return void 0;
+  }
+}
+
+// src/hooks/config.ts
+import { readFileSync } from "fs";
+import { Type, validateToolArguments } from "@ap3x/ai";
+var THookEntry = Type.Object({
+  event: Type.Union(HOOK_EVENT_NAMES.map((n) => Type.Literal(n))),
+  matcher: Type.Optional(Type.String()),
+  command: Type.String({ minLength: 1 }),
+  timeout: Type.Optional(Type.Number({ minimum: 1 })),
+  failMode: Type.Optional(Type.Union([Type.Literal("open"), Type.Literal("closed")])),
+  name: Type.Optional(Type.String())
+});
+var THooksFile = Type.Object({
+  hooks: Type.Array(THookEntry)
+});
+var HookConfigError = class extends Error {
+  constructor(file, detail) {
+    super(`invalid hook config ${file}: ${detail}`);
+    this.file = file;
+    this.name = "HookConfigError";
+  }
+  file;
+};
+function validateShape(file, candidate) {
+  const syntheticTool = {
+    name: "hooks_config",
+    description: "",
+    parameters: THooksFile
+  };
+  try {
+    return validateToolArguments(syntheticTool, {
+      type: "toolCall",
+      id: "hooks-config",
+      name: "hooks_config",
+      arguments: candidate
+    });
+  } catch (error) {
+    throw new HookConfigError(file, error instanceof Error ? error.message : String(error));
+  }
+}
+function parseHooksFile(file, content) {
+  let raw;
+  try {
+    raw = JSON.parse(content);
+  } catch (error) {
+    throw new HookConfigError(
+      file,
+      `not valid JSON (${error instanceof Error ? error.message : String(error)})`
+    );
+  }
+  return validateShape(file, raw).hooks;
+}
+function loadHooksFiles(paths) {
+  const loaded = [];
+  for (const file of paths) {
+    let content;
+    try {
+      content = readFileSync(file, "utf-8");
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw new HookConfigError(
+        file,
+        `cannot read: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    loaded.push({ file, entries: parseHooksFile(file, content) });
+  }
+  return loaded;
+}
+var GATING = /* @__PURE__ */ new Set([
+  "PreToolUse",
+  "SubagentStart",
+  "PreCompact",
+  "Stop"
+]);
+function hooksFromEntries(entries) {
+  return entries.map((entry) => {
+    const timeout = entry.timeout ?? (GATING.has(entry.event) ? DEFAULT_GATING_TIMEOUT_MS : DEFAULT_HOOK_TIMEOUT_MS);
+    return {
+      event: entry.event,
+      ...entry.matcher !== void 0 ? { matcher: entry.matcher } : {},
+      timeout,
+      ...entry.failMode !== void 0 ? { failMode: entry.failMode } : {},
+      name: entry.name ?? entry.command,
+      handler: async (payload) => {
+        const result = await runShellHook(entry.command, JSON.stringify(payload), timeout);
+        return shellDecision(entry.event, result);
+      }
+    };
+  });
+}
+export {
+  DEFAULT_GATING_TIMEOUT_MS,
+  DEFAULT_HOOK_TIMEOUT_MS,
+  HOOK_EVENT_NAMES,
+  HookConfigError,
+  HookEngine,
+  HookExecutionError,
+  HookTimeoutError,
+  QueuedSink,
+  TracePipeline,
+  TraceWriter,
+  attachSwarmHooks,
+  childContext,
+  createHookAgentHooks,
+  currentTraceContext,
+  defineHook,
+  enableDelegationSpans,
+  globMatch,
+  hooksFromEntries,
+  loadHooksFiles,
+  newTraceContext,
+  observeAgent,
+  observeSwarms,
+  parseHooksFile,
+  parseTraceFile,
+  runInTrace,
+  runShellHook,
+  shellDecision,
+  summarizeTrace,
+  userMessage,
+  withSpan
+};