@amsterdamdatalabs/enact-operator 0.1.2

package/runtime/hooks/shared/_toolGuards.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * _toolGuards.mjs — Self-contained runtime tool-guard suite (no build step).
+ *
+ * This is the SINGLE SOURCE OF TRUTH for the five guard functions at runtime.
+ * src/toolGuardHooks.ts re-exports logic by importing from this file so that
+ * guard logic lives here once.
+ *
+ * Twin note: if TS-importing-this-.mjs ever breaks the build, keep src/toolGuardHooks.ts
+ * as a deliberate twin and add a comment in both files pointing to each other.
+ *
+ * Run: node -e "import('./_toolGuards.mjs').then(m => console.log('OK', typeof m.runToolGuards))"
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ── toolOutputTruncator ───────────────────────────────────────────────────────
+
+/**
+ * Truncates large tool output — but ONLY for successful (exitCode === 0) runs.
+ * Error output (non-zero exitCode) is always preserved in full so diagnostics
+ * are never lost.
+ *
+ * @param {{ exitCode: number, output: string, maxLength?: number }} input
+ * @returns {{ output: string, truncated: boolean }}
+ */
+export function toolOutputTruncator({ exitCode, output, maxLength = 8_000 }) {
+  if (exitCode !== 0) {
+    return { output, truncated: false };
+  }
+  if (output.length <= maxLength) {
+    return { output, truncated: false };
+  }
+  const truncated = `${output.slice(0, maxLength)}\n[output truncated: ${output.length - maxLength} chars omitted]`;
+  return { output: truncated, truncated: true };
+}
+
+// ── jsonErrorRecovery ─────────────────────────────────────────────────────────
+
+/**
+ * Attempts to parse a JSON string. On failure, surfaces the ORIGINAL parse
+ * error text — never silently returns a default.
+ *
+ * @param {string} raw
+ * @returns {{ attempted: boolean, recovered: boolean, value?: unknown, errorMessage?: string }}
+ */
+export function jsonErrorRecovery(raw) {
+  const trimmed = String(raw ?? '').trim();
+  if (!trimmed || !/^[\[{]/.test(trimmed)) {
+    return { attempted: false, recovered: false };
+  }
+  try {
+    const value = JSON.parse(trimmed);
+    return { attempted: true, recovered: true, value };
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err);
+    return { attempted: true, recovered: false, errorMessage };
+  }
+}
+
+// ── directoryAgentsInjector ───────────────────────────────────────────────────
+
+/**
+ * Injects AGENTS.md content from the working directory when the file exists.
+ * No injection when AGENTS.md is absent.
+ *
+ * @param {{ workingDirectory: string }} input
+ * @returns {{ injected: boolean, content?: string }}
+ */
+export function directoryAgentsInjector({ workingDirectory }) {
+  const filePath = join(workingDirectory, 'AGENTS.md');
+  if (!existsSync(filePath)) {
+    return { injected: false };
+  }
+  const content = readFileSync(filePath, 'utf8');
+  return { injected: true, content };
+}
+
+// ── directoryReadmeInjector ───────────────────────────────────────────────────
+
+/**
+ * Injects README.md content from the working directory when the file exists.
+ * No injection when README.md is absent.
+ *
+ * @param {{ workingDirectory: string }} input
+ * @returns {{ injected: boolean, content?: string }}
+ */
+export function directoryReadmeInjector({ workingDirectory }) {
+  const filePath = join(workingDirectory, 'README.md');
+  if (!existsSync(filePath)) {
+    return { injected: false };
+  }
+  const content = readFileSync(filePath, 'utf8');
+  return { injected: true, content };
+}
+
+// ── readImageResizer ──────────────────────────────────────────────────────────
+
+// Threshold: only replace if the base64 payload exceeds this character count.
+const IMAGE_RESIZE_THRESHOLD = 200;
+
+// Image data URI prefix pattern
+const IMAGE_DATA_URI_RE = /^data:image\/[a-z]+;base64,/i;
+
+/**
+ * Detects image data URIs in tool output and replaces oversized ones with a
+ * compact placeholder. Does NOT alter non-image tool output.
+ *
+ * @param {{ toolName: string, output: string, maxDimension?: number }} input
+ * @returns {{ output: string, resized: boolean }}
+ */
+export function readImageResizer({ output }) {
+  if (!IMAGE_DATA_URI_RE.test(output)) {
+    return { output, resized: false };
+  }
+  // Strip the data URI prefix to measure the raw base64 payload length
+  const payloadStart = output.indexOf(',') + 1;
+  const payloadLength = output.length - payloadStart;
+  if (payloadLength <= IMAGE_RESIZE_THRESHOLD) {
+    return { output, resized: false };
+  }
+  // Replace the oversized data URI with a compact placeholder
+  const placeholder = `[image data omitted: ${output.length} chars]`;
+  return { output: placeholder, resized: true };
+}
+
+// ── looksLikeJson ─────────────────────────────────────────────────────────────
+
+/**
+ * Cheap structural check: is this string plausibly a JSON document?
+ * Plain tool stdout (ls/find/git output) and empty payloads are NOT JSON and
+ * must never be flagged as "parse errors". Only output that is trimmed,
+ * non-empty, and starts with an object/array opener is worth attempting.
+ *
+ * @param {string} raw
+ * @returns {boolean}
+ */
+export function looksLikeJson(raw) {
+  if (typeof raw !== 'string') return false;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return false;
+  const first = trimmed[0];
+  return first === '{' || first === '[';
+}
+
+// ── Dispatcher integration ────────────────────────────────────────────────────
+
+/**
+ * Build handler entries for a PostToolUse event context.
+ *
+ * @param {{ toolName: string, output: string, exitCode: number, workingDirectory?: string }} ctx
+ * @returns {Array<{ id: string, run: () => Promise<{ hookSpecificOutput: { additionalContext: string }, exitCode: number, stderr: string }> }>}
+ */
+export function buildToolGuardHandlers(ctx) {
+  const workingDirectory = ctx.workingDirectory ?? process.cwd();
+
+  return [
+    {
+      id: 'toolOutputTruncator',
+      run: async () => {
+        const result = toolOutputTruncator({ exitCode: ctx.exitCode, output: ctx.output });
+        return {
+          hookSpecificOutput: { additionalContext: result.truncated ? '[output truncated]' : '' },
+          exitCode: 0,
+          stderr: '',
+        };
+      },
+    },
+    {
+      id: 'jsonErrorRecovery',
+      run: async () => {
+        // Only attempt recovery on output that is actually JSON-shaped. Plain
+        // text / empty tool stdout must never be reported as a parse error.
+        if (!looksLikeJson(ctx.output)) {
+          return { hookSpecificOutput: { additionalContext: '' }, exitCode: 0, stderr: '' };
+        }
+        const result = jsonErrorRecovery(ctx.output);
+        return {
+          hookSpecificOutput: {
+            additionalContext: !result.recovered && result.errorMessage
+              ? `[json parse error: ${result.errorMessage}]`
+              : '',
+          },
+          exitCode: 0,
+          stderr: '',
+        };
+      },
+    },
+    // NOTE: directoryAgentsInjector / directoryReadmeInjector are intentionally
+    // NOT in the PostToolUse chain. AGENTS.md / README.md are loaded once at
+    // SessionStart; re-injecting the full file after every tool call floods the
+    // context window. The standalone functions remain exported for SessionStart
+    // / on-demand consumers.
+    {
+      id: 'readImageResizer',
+      run: async () => {
+        const result = readImageResizer({ toolName: ctx.toolName, output: ctx.output });
+        return {
+          hookSpecificOutput: { additionalContext: result.resized ? '[image resized for context]' : '' },
+          exitCode: 0,
+          stderr: '',
+        };
+      },
+    },
+  ];
+}
+
+/**
+ * Run all guard handlers in order, aggregate their additionalContext strings.
+ *
+ * @param {{ toolName: string, output: string, exitCode: number, workingDirectory?: string }} ctx
+ * @returns {Promise<{ hookSpecificOutput: { additionalContext: string } }>}
+ */
+export async function runToolGuards(ctx) {
+  const handlers = buildToolGuardHandlers(ctx);
+  const parts = [];
+
+  for (const handler of handlers) {
+    try {
+      const result = await handler.run();
+      if (result.exitCode !== 0) {
+        parts.push(`[hook error exit=${result.exitCode}: ${result.stderr.slice(0, 120)}]`);
+      } else if (result.hookSpecificOutput.additionalContext) {
+        parts.push(result.hookSpecificOutput.additionalContext);
+      }
+    } catch (err) {
+      parts.push(`[hook error: ${err instanceof Error ? err.message : String(err)}]`);
+    }
+  }
+
+  return {
+    hookSpecificOutput: {
+      additionalContext: parts.join('\n'),
+    },
+  };
+}

package/runtime/hooks/shared/config.mjs

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import * as TOML from "@iarna/toml";
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function deepMerge(base, overlay) {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    const existing = out[key];
+    if (isRecord(existing) && isRecord(value)) {
+      out[key] = deepMerge(existing, value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function readTomlIfExists(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return TOML.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function configFileName() {
+  return process.env.NODE_ENV === "production" ? "config.prd.toml" : "config.toml";
+}
+
+function defaultWatchdogDir() {
+  return join(homedir(), ".enact", "watchdog");
+}
+
+function normalizeWatchdogDir(resolvedPath) {
+  return resolvedPath.endsWith(".ndjson") ? dirname(resolvedPath) : resolvedPath;
+}
+
+function findNearestAncestorWithFile(startDir, fileName) {
+  let current = resolve(startDir);
+  while (true) {
+    const candidate = join(current, fileName);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+export function findWorkspaceConfigPath(startDir = process.cwd()) {
+  return findNearestAncestorWithFile(startDir, configFileName());
+}
+
+export function findGitRoot(startDir = process.cwd()) {
+  const start = resolve(startDir);
+  const tmpRoot = resolve(tmpdir());
+  let cur = start;
+  while (true) {
+    const candidate = join(cur, ".git");
+    if (existsSync(candidate)) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    if (parent === tmpRoot && cur !== tmpRoot) break;
+    cur = parent;
+  }
+  return null;
+}
+
+export function resolveWorkspaceRoot(startDir = process.cwd()) {
+  const workspaceConfigPath = findWorkspaceConfigPath(startDir);
+  if (workspaceConfigPath) return dirname(workspaceConfigPath);
+  return findGitRoot(startDir) ?? resolve(startDir);
+}
+
+function loadConfigContext(startDir = process.cwd()) {
+  const globalConfigDir = join(homedir(), ".enact", "operator");
+  const globalConfigPath = join(globalConfigDir, configFileName());
+  const workspaceConfigPath = findWorkspaceConfigPath(startDir);
+  return {
+    globalConfigDir,
+    workspaceConfigPath,
+    workspaceConfigDir: workspaceConfigPath ? dirname(workspaceConfigPath) : null,
+    globalConfig: readTomlIfExists(globalConfigPath),
+    workspaceConfig: workspaceConfigPath ? readTomlIfExists(workspaceConfigPath) : null,
+  };
+}
+
+function expandPathValue(raw, sourceDir) {
+  const trimmed = raw.trim();
+  if (trimmed === "~") return homedir();
+  if (trimmed.startsWith("~/")) return join(homedir(), trimmed.slice(2));
+  if (isAbsolute(trimmed)) return trimmed;
+  return resolve(sourceDir, trimmed);
+}
+
+function resolveDeclaredString(workspaceValue, globalValue, ctx) {
+  if (typeof workspaceValue === "string" && workspaceValue.trim() && ctx.workspaceConfigDir) {
+    return expandPathValue(workspaceValue, ctx.workspaceConfigDir);
+  }
+  if (typeof globalValue === "string" && globalValue.trim()) {
+    return expandPathValue(globalValue, ctx.globalConfigDir);
+  }
+  return null;
+}
+
+export function readMergedOperatorConfig(startDir = process.cwd()) {
+  const ctx = loadConfigContext(startDir);
+  const parts = [ctx.globalConfig, ctx.workspaceConfig].filter(Boolean);
+  if (parts.length === 0) return null;
+  let merged = {};
+  for (const part of parts) {
+    merged = deepMerge(merged, part);
+  }
+  return merged;
+}
+
+export function resolveWatchdogDir(startDir = process.cwd()) {
+  const ctx = loadConfigContext(startDir);
+  const resolved = resolveDeclaredString(
+    ctx.workspaceConfig?.agent?.watchdog_dir,
+    ctx.globalConfig?.agent?.watchdog_dir,
+    ctx,
+  );
+  if (resolved) return normalizeWatchdogDir(resolved);
+  return defaultWatchdogDir();
+}
+
+export function readWorkspaceStorage(root = resolveWorkspaceRoot()) {
+  const workspaceConfigPath = findWorkspaceConfigPath(root);
+  if (!workspaceConfigPath) return join(root, ".enact", "operator");
+  const workspaceConfig = readTomlIfExists(workspaceConfigPath);
+  const storage = workspaceConfig?.operator?.storage;
+  if (typeof storage !== "string" || !storage.trim()) {
+    return join(root, ".enact", "operator");
+  }
+  return expandPathValue(storage, dirname(workspaceConfigPath));
+}

package/runtime/hooks/shared/layout-dir.mjs

@@ -0,0 +1,12 @@
+import { join } from "node:path";
+import { rootDir } from "./root-dir.mjs";
+import { readWorkspaceStorage } from "./config.mjs";
+
+/** Canonical operator layout root for hook scripts (declared by [operator].storage). */
+export function layoutDir(root = rootDir()) {
+  return readWorkspaceStorage(root);
+}
+
+export function layoutPath(root, ...segments) {
+  return join(layoutDir(root), ...segments);
+}

package/runtime/hooks/shared/observability.mjs

@@ -0,0 +1,257 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readMergedOperatorConfig, resolveWatchdogDir } from "./config.mjs";
+
+function readWorkspaceConfig(startDir = process.cwd()) {
+  return readMergedOperatorConfig(startDir);
+}
+
+function operatorFlag(name, startDir = process.cwd()) {
+  const config = readWorkspaceConfig(startDir);
+  const value = config?.operator?.[name];
+  return typeof value === "boolean" ? value : false;
+}
+
+function resolveSessionId(payload) {
+  return typeof payload?.session_id === "string" && payload.session_id.trim()
+    ? payload.session_id
+    : "unknown";
+}
+
+function resolveRunId(payload) {
+  if (typeof payload?.transcript_id === "string" && payload.transcript_id.trim()) {
+    return payload.transcript_id;
+  }
+  return resolveSessionId(payload);
+}
+
+function requiredFieldWarnings(event) {
+  const required = ["schema_version", "source", "event_type", "session_id", "run_id", "ts"];
+  if (!operatorFlag("observability_debug", event?.payload?.cwd ?? process.cwd())) return [];
+  return required.filter((key) => !event[key]);
+}
+
+async function fallbackEmitEvent(event, startDir = process.cwd()) {
+  for (const missing of requiredFieldWarnings(event)) {
+    console.error(`[observability] warn: missing field ${missing}`);
+  }
+
+  const config = readWorkspaceConfig(startDir);
+  const watchdogDir = resolveWatchdogDir(startDir);
+  mkdirSync(watchdogDir, { recursive: true });
+  const ndjsonPath = join(watchdogDir, "operator-events.ndjson");
+  appendFileSync(ndjsonPath, `${JSON.stringify(event)}\n`, "utf8");
+
+  const iggyUrl = config?.watchdog?.iggy_http_url;
+  if (typeof iggyUrl !== "string" || !iggyUrl.trim()) {
+    throw new Error("Missing [watchdog].iggy_http_url in merged operator config");
+  }
+  const body = {
+    partitioning: { kind: "balanced", value: "" },
+    messages: [
+      {
+        id: 0,
+        payload: Buffer.from(JSON.stringify(event)).toString("base64"),
+      },
+    ],
+  };
+
+  try {
+    const authHeader = await resolveIggyAuthHeader(iggyUrl, startDir);
+    const response = await fetch(`${iggyUrl}/streams/enact-telemetry/topics/worker_telemetry/messages`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: authHeader,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(500),
+    });
+    if (!response.ok) {
+      throw new Error(`Iggy publish failed with ${response.status}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("ECONNREFUSED") || message.includes("fetch failed")) {
+      return;
+    }
+    console.error(`[observability] ${message}`);
+  }
+}
+
+async function resolveIggyAuthHeader(baseUrl, startDir = process.cwd()) {
+  const config = readWorkspaceConfig(startDir);
+  const rawToken = process.env.IGGY_HTTP_ACCESS_TOKEN ?? process.env.IGGY_ACCESS_TOKEN;
+  if (typeof rawToken === "string" && rawToken.trim()) {
+    return `Bearer ${rawToken.trim()}`;
+  }
+
+  const username = typeof config?.watchdog?.iggy_username === "string" && config.watchdog.iggy_username.trim()
+    ? config.watchdog.iggy_username
+    : "iggy";
+  const password = typeof config?.watchdog?.iggy_password === "string" && config.watchdog.iggy_password.trim()
+    ? config.watchdog.iggy_password
+    : "iggy";
+  const response = await fetch(`${baseUrl}/users/login`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ username, password }),
+    signal: AbortSignal.timeout(500),
+  });
+  if (!response.ok) {
+    throw new Error(`Iggy login failed with ${response.status}`);
+  }
+
+  const payload = await response.json();
+  const token = payload?.access_token?.token;
+  if (!token) {
+    throw new Error("Iggy login response missing access token");
+  }
+  return `Bearer ${token}`;
+}
+
+async function loadEmitEvent() {
+  const repoRoot = join(dirname(new URL(import.meta.url).pathname), "..", "..", "..");
+  try {
+    const mod = await import(join(repoRoot, "dist", "shared", "observability", "emit.js"));
+    if (typeof mod.emitEvent === "function") {
+      return mod.emitEvent;
+    }
+  } catch {
+    // Fall through to inline fallback emitter when dist is absent in tests/dev.
+  }
+  return fallbackEmitEvent;
+}
+
+export async function emitOperatorEvent(event) {
+  const emitEvent = await loadEmitEvent();
+  await emitEvent(event, event?.payload?.cwd ?? process.cwd());
+}
+
+export async function emitHookFired({
+  payload,
+  hookEvent,
+  outcome,
+  latencyMs,
+  toolName,
+  preset = "enact-operator",
+  extraPayload = {},
+}) {
+  await emitOperatorEvent({
+    schema_version: "enact.raw.v1",
+    source: "enact-operator",
+    event_type: "hook.fired",
+    session_id: resolveSessionId(payload),
+    run_id: resolveRunId(payload),
+    ts: new Date().toISOString(),
+    payload: {
+      hook_event: hookEvent,
+      preset,
+      outcome,
+      latency_ms: latencyMs,
+      ...(toolName ? { tool_name: toolName } : {}),
+      cwd: payload?.cwd ?? process.cwd(),
+      ...extraPayload,
+    },
+  });
+}
+
+export async function emitHookFailed({
+  payload,
+  hookEvent,
+  error,
+  latencyMs,
+  toolName,
+  preset = "enact-operator",
+  extraPayload = {},
+}) {
+  await emitOperatorEvent({
+    schema_version: "enact.raw.v1",
+    source: "enact-operator",
+    event_type: "hook.failed",
+    session_id: resolveSessionId(payload),
+    run_id: resolveRunId(payload),
+    ts: new Date().toISOString(),
+    payload: {
+      hook_event: hookEvent,
+      preset,
+      tool_name: toolName ?? null,
+      cwd: payload?.cwd ?? process.cwd(),
+      error_message: error instanceof Error ? error.message : String(error),
+      latency_ms: latencyMs,
+      ...extraPayload,
+    },
+  });
+}
+
+export function registerHookFailureTrap({
+  payload,
+  hookEvent,
+  startedAt,
+  toolName,
+  preset = "enact-operator",
+  extraPayload = {},
+}) {
+  let completed = false;
+
+  const emitFailureAndExit = async (reason) => {
+    if (completed) return;
+    completed = true;
+    try {
+      console.error(reason instanceof Error ? (reason.stack ?? reason.message) : String(reason));
+      await emitHookFailed({
+        payload,
+        hookEvent,
+        error: reason,
+        latencyMs: Date.now() - startedAt,
+        toolName,
+        preset,
+        extraPayload,
+      });
+    } finally {
+      process.exit(1);
+    }
+  };
+
+  const uncaughtHandler = (error) => {
+    void emitFailureAndExit(error);
+  };
+
+  const rejectionHandler = (reason) => {
+    void emitFailureAndExit(reason);
+  };
+
+  process.once("uncaughtException", uncaughtHandler);
+  process.once("unhandledRejection", rejectionHandler);
+
+  return () => {
+    completed = true;
+    process.removeListener("uncaughtException", uncaughtHandler);
+    process.removeListener("unhandledRejection", rejectionHandler);
+  };
+}
+
+export async function emitStopVerdict({
+  payload,
+  verdict,
+  blockers,
+  stopHookActive,
+  latencyMs,
+}) {
+  await emitOperatorEvent({
+    schema_version: "enact.raw.v1",
+    source: "enact-operator",
+    event_type: "stop.verdict",
+    session_id: resolveSessionId(payload),
+    run_id: resolveRunId(payload),
+    ts: new Date().toISOString(),
+    payload: {
+      'openinference.span.kind': 'CHAIN',
+      'enact.verdict': verdict,
+      'enact.blockers': blockers,
+      'enact.stop_hook_active': stopHookActive,
+      'enact.duration_ms': latencyMs,
+    },
+  });
+}

package/runtime/hooks/shared/root-dir.mjs

@@ -0,0 +1,9 @@
+import { resolveWorkspaceRoot } from "./config.mjs";
+
+export function rootDirFrom(startDir = process.cwd()) {
+  return resolveWorkspaceRoot(startDir);
+}
+
+export function rootDir() {
+  return rootDirFrom(process.cwd());
+}

package/runtime/hooks/stop.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import "./lifecycle/stop.mjs";
+

package/runtime/hooks/subagent-tracker.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import "./subagents/subagent-tracker.mjs";
+