@amsterdamdatalabs/enact-operator 0.1.2

package/runtime/hooks/lifecycle/pre-compact.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+import { rootDirFrom } from "../shared/root-dir.mjs";
+import { layoutPath } from "../shared/layout-dir.mjs";
+import { emitHookFired } from "../shared/observability.mjs";
+import { readHooksVerbose, verboseLog } from "../shared/_lib.mjs";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const repoRoot = join(__dirname, "..", "..", "..");
+const { readOperatorAuthority } = await import("@amsterdamdatalabs/enact-operator/authority");
+const { buildContinuationGuidance, hasPendingLocalTasks } = await import("@amsterdamdatalabs/enact-operator/continuation");
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return {};
+  }
+}
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function appendLedger(root, entry) {
+  const dir = layoutPath(root, "logs");
+  mkdirSync(dir, { recursive: true });
+  const line = JSON.stringify({
+    schemaVersion: 1,
+    id: `ledger_${randomUUID().replace(/-/g, "").slice(0, 13)}`,
+    ...entry,
+    createdAt: new Date().toISOString(),
+  });
+  appendFileSync(layoutPath(root, "logs", "ledger.json"), line + "\n");
+}
+
+const payload = readStdin();
+const root = rootDirFrom(payload?.cwd ?? process.cwd());
+const startedAt = Date.now();
+
+const ultraworkState = readJson(layoutPath(root, "state", "ultrawork.json"), null);
+const ralphState = readJson(layoutPath(root, "state", "ralph.json"), null);
+
+const ultraworkActive = !!(ultraworkState && ultraworkState.active);
+const ultraworkPhase = ultraworkState?.phase ?? null;
+const ralphActive = !!(ralphState && ralphState.active);
+const ralphPhase = ralphState?.phase ?? null;
+
+const timestamp = new Date().toISOString();
+
+// Log to hooks.log
+try {
+  mkdirSync(layoutPath(root, "logs"), { recursive: true });
+  appendFileSync(
+    layoutPath(root, "logs", "hooks.log"),
+    `${timestamp} PreCompact ultraworkActive=${ultraworkActive} ralphActive=${ralphActive}\n`,
+    "utf8",
+  );
+} catch {
+  // best-effort
+}
+
+// Append to ledger
+try {
+  appendLedger(root, {
+    kind: "session",
+    action: "pre_compact",
+    detail: "Context compaction triggered",
+    actor: "enact-operator-hook",
+    metadata: { ultraworkPhase, ultraworkActive, ralphPhase, ralphActive },
+  });
+} catch {
+  // best-effort
+}
+
+// Persist pending local task context for compaction recovery
+try {
+  const authority = readOperatorAuthority(root);
+  const guidance = buildContinuationGuidance(authority);
+  if (hasPendingLocalTasks(guidance)) {
+    const compactionContext = {
+      capturedAt: timestamp,
+      pendingLocalTaskIds: guidance.pendingLocalTaskIds,
+      pendingLocalTaskTitles: guidance.pendingLocalTaskTitles,
+      resumeHint: guidance.resumeHint,
+      lane: guidance.lane,
+      laneId: guidance.laneId,
+    };
+    writeFileSync(
+      layoutPath(root, "state", "compaction-context.json"),
+      JSON.stringify(compactionContext, null, 2),
+      "utf8",
+    );
+  }
+} catch {
+  // best-effort
+}
+
+await emitHookFired({
+  payload,
+  hookEvent: "PreCompact",
+  outcome: "noop",
+  latencyMs: Date.now() - startedAt,
+});
+if (readHooksVerbose(root)) {
+  const detail = ultraworkActive
+    ? `ultrawork active (phase: ${ultraworkPhase})`
+    : ralphActive
+      ? `ralph active (phase: ${ralphPhase})`
+      : "no autonomous lane active";
+  verboseLog("pre-compact", `context compaction triggered — ${detail}`);
+}
+
+process.stdout.write(JSON.stringify({ continue: true }));

package/runtime/hooks/lifecycle/session-start.mjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+/**
+ * Phase 7 — Session-start: consume prior stop verdict.
+ * At session start, reads the last stop-verdict artifact.
+ * If the verdict is deny and NOT yet acknowledged, surfaces a system-reminder-style
+ * context block describing the prior unsafe stop attempt with a concrete checklist.
+ * Calls markStopVerdictAcknowledged after surfacing.
+ * Allow / already-acknowledged verdicts pass silently.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readMergedOperatorConfig } from "../shared/config.mjs";
+import { rootDirFrom } from "../shared/root-dir.mjs";
+import { layoutDir, layoutPath } from "../shared/layout-dir.mjs";
+import { emitHookFired, registerHookFailureTrap } from "../shared/observability.mjs";
+import { readHooksVerbose, verboseLog } from "../shared/_lib.mjs";
+// _continuation.mjs: self-contained runtime continuation orchestrator (no dist/ dependency).
+// Twin: src/continuationOrchestrator.ts (typed twin — keep in sync).
+import { buildContinuationContext } from "../shared/_continuation.mjs";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const repoRoot = join(__dirname, "..", "..", "..");
+const { touchContinuationActivity, formatMandatoryLocalContinuationContext } = await import("@amsterdamdatalabs/enact-operator/continuation");
+const { captureActiveWorkflows, formatContinuationContext } = await import("@amsterdamdatalabs/enact-operator/hookContinuation");
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(value, null, 2), "utf8");
+}
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Format the unsafe-stop context block surfaced to the operator.
+ * Returns a system-reminder-style string describing the prior stop attempt.
+ */
+function formatUnsafeStopContext(verdict) {
+  const lines = [
+    "PRIOR UNSAFE STOP DETECTED",
+    `The previous session attempted to stop while work was still open (${verdict.capturedAt}).`,
+    `Stop policy verdict: DENY (${verdict.reasons.length} blocker(s) remained unresolved).`,
+    "",
+    "Unresolved blockers:",
+  ];
+
+  for (const reason of verdict.reasons) {
+    const laneTag = reason.laneId ? `[${reason.lane}:${reason.laneId}]` : `[${reason.lane}]`;
+    lines.push(`  - ${laneTag} ${reason.blocker}`);
+  }
+
+  lines.push(
+    "",
+    "Resolve checklist before stopping again:",
+    "  [ ] Review each blocker above and address it explicitly.",
+    "  [ ] If Ralph is active: advance to 'completed' or 'aborted' and pass all verification gates.",
+  "  [ ] If Ultrawork is active: advance to 'completed' or 'aborted' and close all linked tasks.",
+  "  [ ] If Team is active: ensure all claimed tasks are completed and all reviews have verdicts.",
+    "  [ ] Run operator_stop_evaluate (dry-run) to confirm stop policy is now allow before stopping.",
+    "  [ ] Or use operator_stop_acknowledge with an explicit reason to override (operator escape hatch).",
+    "",
+    "This notice will not repeat -- it has been acknowledged for this session.",
+  );
+
+  return lines.join("\n");
+}
+
+function readContinuationState(path) {
+  return readJson(path, {
+    status: "idle",
+    resumeHint: null,
+  });
+}
+
+function buildDelegatedSessionScopes(continuationState, activeWorkflows) {
+  const scopes = [];
+  const pushScope = (lane, laneId = null) => {
+    if (!lane || lane === "none") return;
+    const key = `${lane}:${laneId ?? ""}`;
+    if (scopes.some((scope) => `${scope.lane}:${scope.laneId ?? ""}` === key)) return;
+    scopes.push({ lane, laneId });
+  };
+
+  pushScope(continuationState.lane, continuationState.laneId ?? null);
+  if (activeWorkflows.ralph?.active) pushScope("ralph", activeWorkflows.ralph.id);
+  if (activeWorkflows.ultrawork?.active) pushScope("ultrawork", activeWorkflows.ultrawork.id);
+  if (activeWorkflows.autopilot?.active) pushScope("autopilot", activeWorkflows.autopilot.id);
+  if (activeWorkflows.team?.active) pushScope("team", activeWorkflows.team.id);
+
+  return scopes;
+}
+
+function delegatedSessionMatchesScope(session, scope) {
+  if (session.parentLane !== scope.lane) return false;
+  if (!scope.laneId) return true;
+  if (!session.parentLaneId) return true;
+  return session.parentLaneId === scope.laneId;
+}
+
+function buildDelegatedSessionNote(continuationCtx, continuationState, activeWorkflows) {
+  if (!continuationCtx.hasDelegatedSessions) return null;
+  const scopes = buildDelegatedSessionScopes(continuationState, activeWorkflows);
+  if (scopes.length === 0) return null;
+
+  const focusSessions = [];
+  for (const session of continuationCtx.delegatedSessions) {
+    if (!scopes.some((scope) => delegatedSessionMatchesScope(session, scope))) continue;
+    if (focusSessions.some((existing) => existing.continuationId === session.continuationId)) continue;
+    focusSessions.push(session);
+  }
+
+  const focusIds = new Set(focusSessions.map((session) => session.continuationId));
+  const outsideStaleCount = continuationCtx.delegatedSessions.filter(
+    (session) => session.status === "stale" && !focusIds.has(session.continuationId),
+  ).length;
+
+  if (focusSessions.length === 0 && outsideStaleCount === 0) return null;
+
+  const sentences = [];
+  if (focusSessions.length > 0) {
+    sentences.push(
+      `Delegated sessions for current lane: ${focusSessions.map((session) => `${session.continuationId} (${session.kind}, ${session.status})`).join(", ")}.`,
+    );
+  }
+  if (outsideStaleCount > 0) {
+    const noun = outsideStaleCount === 1 ? "session exists" : "sessions exist";
+    sentences.push(`${outsideStaleCount} stale delegated ${noun} outside the current lane.`);
+  }
+  sentences.push("Check delegated session status before stopping.");
+  return sentences.join(" ");
+}
+
+/**
+ * Build a workspace domain identity block for session-start context injection.
+ *
+ * Gate: only fires when [hooks].prime_workspace_domain = true in the workspace
+ * config.toml (opt-in, default false per R2 risk mitigation).
+ *
+ * Reads domain metadata from the [workspace] section and injects a compact
+ * identity block so the agent knows its domain context at session start without
+ * requiring explicit user instruction. Does NOT inject vault content — only
+ * metadata (INV-002: no cross-workspace content leakage).
+ *
+ * Returns a string block to push onto contextSections, or null to skip silently.
+ */
+function buildWorkspaceDomainPrimingBlock(workspaceRoot) {
+  const config = readMergedOperatorConfig(workspaceRoot);
+  if (!config) return null;
+
+  // Gate: opt-in flag must be explicitly true
+  if (config?.hooks?.prime_workspace_domain !== true) return null;
+
+  const ws = config?.workspace;
+  if (!ws || !ws.name) {
+    // [workspace] section absent — nothing to inject (R2 mitigation: default to no injection)
+    return null;
+  }
+
+  const lines = [
+    "WORKSPACE DOMAIN CONTEXT",
+    `This agent session is operating inside the "${ws.name}" workspace.`,
+  ];
+
+  if (ws.domain) {
+    lines.push(`Domain: ${ws.domain}`);
+  }
+  if (ws.ontology) {
+    lines.push(`Ontology: ${ws.ontology}`);
+  }
+  if (ws.primary_language) {
+    lines.push(`Primary language: ${ws.primary_language}`);
+  }
+  if (Array.isArray(ws.constraint_categories) && ws.constraint_categories.length > 0) {
+    lines.push(`Key constraint categories: ${ws.constraint_categories.join(", ")}`);
+  }
+
+  lines.push(
+    "",
+    "Use domain-specific vocabulary, entities, and constraints from the workspace wiki vault",
+    "when answering questions. Prefer wiki vault content over generic LLM knowledge for",
+    "domain queries (products, formulations, regulations, SKUs, etc.).",
+  );
+
+  return lines.join("\n");
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+const payload = readStdin();
+const root = rootDirFrom(payload?.cwd ?? process.cwd());
+const startedAt = Date.now();
+const completeHook = registerHookFailureTrap({
+  payload,
+  hookEvent: "SessionStart",
+  startedAt,
+});
+const operatorLayout = layoutDir(root);
+mkdirSync(layoutPath(root, "logs"), { recursive: true });
+mkdirSync(layoutPath(root, "state"), { recursive: true });
+const runtime = readJson(layoutPath(root, "state", "operator-hook-runtime.json"), {});
+
+const activeWorkflows = captureActiveWorkflows(root);
+
+appendFileSync(layoutPath(root, "logs", "hooks.log"), `${new Date().toISOString()} SessionStart ${JSON.stringify(payload)}\n`, "utf8");
+writeJson(layoutPath(root, "state", "operator-hook-runtime.json"), {
+  ...runtime,
+  lastSessionStartAt: new Date().toISOString(),
+  cwd: root,
+  trigger: payload.session_type ?? "unknown",
+  activeWorkflows,
+});
+touchContinuationActivity(root, "session-start");
+
+const workflowContext = formatContinuationContext(activeWorkflows);
+
+// Build continuation context via _continuation.mjs (no dist/ dependency).
+// Wires all five predecessor surfaces: compaction-context, delegated-session ledger,
+// protected-state guard, member-turn injection, and manual-close filter.
+const continuationCtx = buildContinuationContext(operatorLayout);
+const continuationState = continuationCtx.continuationState;
+
+// Build guidance using the lane read from continuation-state.json (Surface 4).
+// pendingLocalTaskIds from continuationCtx feeds formatMandatoryLocalContinuationContext
+// without requiring readOperatorAuthority (dist-free path).
+const guidanceFromCtx = {
+  lane: continuationState.lane,
+  laneId: continuationState.laneId,
+  pendingLocalTaskIds: continuationState.pendingLocalTaskIds,
+  pendingLocalTaskTitles: continuationState.pendingLocalTaskTitles ?? [],
+  resumeHint: continuationState.resumeHint ?? "",
+  pendingTaskIds: continuationState.pendingTaskIds,
+  pendingReviewTaskIds: [],
+  pendingMessageIds: [],
+};
+const mandatoryContinuation = formatMandatoryLocalContinuationContext(guidanceFromCtx, "proceeding with new work");
+
+// Compaction recovery: restore pending local task context (Surface 1).
+// Uses compactionContext from _continuation.mjs (filtered for manual-close via Surface 5).
+const compactionContext = continuationCtx.compactionContext;
+const compactionRecovery = (
+  compactionContext &&
+  compactionContext.pendingLocalTaskIds.length > 0 &&
+  !mandatoryContinuation  // don't double-surface if mandatory is already shown
+)
+  ? `Compaction recovery: resume with pending local task(s) first — ` +
+    `${compactionContext.pendingLocalTaskIds.map((id, i) => `${id} "${compactionContext.pendingLocalTaskTitles?.[i] ?? ''}"`).join(', ')}. ` +
+    `${compactionContext.resumeHint ?? ''}`
+  : null;
+
+// Delegated sessions (Surface 2): focus the current lane and summarize residue.
+const delegatedSessionNote = buildDelegatedSessionNote(
+  continuationCtx,
+  continuationState,
+  activeWorkflows,
+);
+
+const {
+  findHeadQueuedFollowUp,
+  pickFollowUpForReplay,
+  reserveFollowUpReplay,
+  markFollowUpReplayed,
+} = await import("@amsterdamdatalabs/enact-operator/continuationFollowUp");
+const sid = typeof payload.session_id === "string" ? payload.session_id : null;
+const stopDeny = findHeadQueuedFollowUp(root, "stop-deny");
+let replayCandidate = stopDeny;
+if (!replayCandidate && guidanceFromCtx.lane !== "none") {
+  replayCandidate = pickFollowUpForReplay(root, guidanceFromCtx.lane, sid);
+}
+
+// Check for unacknowledged deny verdict from prior session
+const verdictPath = join(operatorLayout, "state", "stop-verdict.json");
+const lastVerdict = readJson(verdictPath, null);
+const contextSections = [];
+
+if (replayCandidate) {
+  const r = reserveFollowUpReplay(root, { followUpId: replayCandidate.id, sessionId: sid });
+  if (r.reserved && r.reinjectionText) {
+    contextSections.push(r.reinjectionText);
+    markFollowUpReplayed(root, replayCandidate.id, sid);
+  }
+}
+
+if (lastVerdict && lastVerdict.outcome === "deny" && !lastVerdict.acknowledgedAt) {
+  // Surface the unsafe-stop context block
+  const unsafeStopContext = formatUnsafeStopContext(lastVerdict);
+  const resumeHint = continuationState.status === "blocked" && continuationState.resumeHint
+    ? `\n\nResume hint: ${continuationState.resumeHint}`
+    : "";
+  contextSections.push(`${unsafeStopContext}${resumeHint}`);
+
+  // Acknowledge: mark as consumed by this session-start so it won't repeat
+  const acknowledged = {
+    ...lastVerdict,
+    acknowledgedAt: new Date().toISOString(),
+    acknowledgedReason: "session-start auto-acknowledge after surfacing to operator",
+  };
+  writeJson(verdictPath, acknowledged);
+}
+
+if (compactionRecovery) {
+  contextSections.push(compactionRecovery);
+}
+
+if (delegatedSessionNote) {
+  contextSections.push(delegatedSessionNote);
+}
+
+if (mandatoryContinuation) {
+  contextSections.push(mandatoryContinuation);
+}
+
+const workspacePrimingBlock = buildWorkspaceDomainPrimingBlock(root);
+if (workspacePrimingBlock) {
+  contextSections.push(workspacePrimingBlock);
+} else if (readHooksVerbose(root)) {
+  // When verbose, emit a note that priming was skipped (not enabled or no [workspace] section)
+  verboseLog("session-start", "workspace domain priming skipped (prime_workspace_domain not set or no [workspace] section)");
+}
+
+contextSections.push(`Operator hook runtime initialized. ${workflowContext}`);
+const additionalContext = contextSections.join("\n\n");
+
+await emitHookFired({
+  payload,
+  hookEvent: "SessionStart",
+  outcome: "noop",
+  latencyMs: Date.now() - startedAt,
+});
+if (readHooksVerbose(root)) {
+  const wfSummary = activeWorkflows?.workflows?.length
+    ? `${activeWorkflows.workflows.length} active workflow(s)`
+    : "no workflows active";
+  verboseLog("session-start", `initialized — ${wfSummary}, ${contextSections.length} context section(s) injected`);
+}
+completeHook();
+process.stdout.write(JSON.stringify({
+  continue: true,
+  hookSpecificOutput: {
+    hookEventName: "SessionStart",
+    additionalContext,
+  },
+}));