@sanctuary-framework/mcp-server 1.2.10 → 1.2.11

package/dist/index.cjs

@@ -16565,6 +16565,306 @@ async function handleSentinelRoute(deps, req, res) {
     return true;
   }
 }
+var HANDOFF_LOG_OBSERVED_OPS = {
+  /** Tau-3 in-process coordination handoff. */
+  LOCAL_HANDOFF: "v1.1_local_handoff",
+  /** Upsilon-1 cross-harness approval (wrapped-agent -> operator). */
+  CROSS_HARNESS_APPROVAL: "cross_harness_approval_aggregated"
+};
+var OBSERVED_OP_LIST = [
+  HANDOFF_LOG_OBSERVED_OPS.LOCAL_HANDOFF,
+  HANDOFF_LOG_OBSERVED_OPS.CROSS_HARNESS_APPROVAL
+];
+var OPERATOR_PSEUDO_AGENT = "operator";
+function makeEntryId(auditEventId) {
+  return crypto.createHash("sha256").update(auditEventId).digest("hex").slice(0, 32);
+}
+var DEFAULT_LIMIT = 50;
+var MAX_LIMIT = 500;
+var AUDIT_QUERY_LIMIT = 1e4;
+var HandoffLog = class {
+  auditLog;
+  fortressId;
+  constructor(opts) {
+    this.auditLog = opts.auditLog;
+    this.fortressId = opts.fortressId;
+  }
+  /** Stable fortress id this HandoffLog reads. */
+  getFortressId() {
+    return this.fortressId;
+  }
+  /**
+   * Query handoffs in chronological-newest-first order. Filters
+   * applied after normalization so the per-event-class shape
+   * differences (sender field name, recipient inference) are handled
+   * once.
+   */
+  async query(opts) {
+    const limit = Math.min(opts.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
+    const queryResult = await this.auditLog.query({
+      ...opts.since !== void 0 ? { since: opts.since } : {},
+      layer: "l2",
+      limit: AUDIT_QUERY_LIMIT
+    });
+    const normalized = [];
+    for (const entry of queryResult.entries) {
+      if (!OBSERVED_OP_LIST.includes(entry.operation)) continue;
+      const handoff = this.normalize(entry);
+      if (!handoff) continue;
+      if (opts.until && handoff.observed_at > opts.until) continue;
+      if (opts.since && handoff.observed_at < opts.since) continue;
+      if (opts.agent_id) {
+        if (handoff.source_agent_id !== opts.agent_id && handoff.target_agent_id !== opts.agent_id) {
+          continue;
+        }
+      }
+      normalized.push(handoff);
+    }
+    normalized.sort((a, b) => a.observed_at < b.observed_at ? 1 : -1);
+    return normalized.slice(0, limit);
+  }
+  /**
+   * Look up a single entry by id. Returns the normalized entry +
+   * the source audit payload for operator-facing detail rendering.
+   * Returns null when no audit entry maps to the given id.
+   */
+  async getEntry(entryId) {
+    const queryResult = await this.auditLog.query({
+      layer: "l2",
+      limit: AUDIT_QUERY_LIMIT
+    });
+    for (const audit of queryResult.entries) {
+      if (!OBSERVED_OP_LIST.includes(audit.operation)) continue;
+      const handoff = this.normalize(audit);
+      if (!handoff) continue;
+      if (handoff.entry_id === entryId) {
+        return { entry: handoff, source_audit_entry: audit };
+      }
+    }
+    return null;
+  }
+  normalize(audit) {
+    const details = audit.details;
+    if (audit.operation === HANDOFF_LOG_OBSERVED_OPS.LOCAL_HANDOFF) {
+      const sender = optString(details, "sender_agent_id");
+      const recipient = optString(details, "recipient_agent_id");
+      if (!sender || !recipient || sender === recipient) return null;
+      const auditEventId = optString(details, "event_id") ?? auditEventIdFallback(audit);
+      return {
+        entry_id: makeEntryId(auditEventId),
+        audit_event_id: auditEventId,
+        source_agent_id: sender,
+        target_agent_id: recipient,
+        observed_at: audit.timestamp,
+        event_class: audit.operation,
+        context_transfer_summary: localHandoffSummary(details, sender, recipient),
+        workflow_link: null
+      };
+    }
+    if (audit.operation === HANDOFF_LOG_OBSERVED_OPS.CROSS_HARNESS_APPROVAL) {
+      const sender = optString(details, "source_harness") ?? optString(details, "source_agent_id");
+      if (!sender) return null;
+      const auditEventId = optString(details, "aggregator_id") ?? auditEventIdFallback(audit);
+      return {
+        entry_id: makeEntryId(auditEventId),
+        audit_event_id: auditEventId,
+        source_agent_id: sender,
+        target_agent_id: OPERATOR_PSEUDO_AGENT,
+        observed_at: audit.timestamp,
+        event_class: audit.operation,
+        context_transfer_summary: crossHarnessSummary(details, sender),
+        workflow_link: null
+      };
+    }
+    return null;
+  }
+};
+function optString(details, key) {
+  if (!details) return null;
+  const value = details[key];
+  if (typeof value !== "string" || value.length === 0) return null;
+  return value;
+}
+function auditEventIdFallback(audit) {
+  return `${audit.timestamp}:${audit.operation}`;
+}
+function localHandoffSummary(details, sender, recipient) {
+  const taskScope = optString(details, "task_scope");
+  const reasonClass = optString(details, "reason_class");
+  if (taskScope) {
+    return `${sender} -> ${recipient} handoff: ${taskScope}`;
+  }
+  if (reasonClass) {
+    return `${sender} -> ${recipient} handoff (${reasonClass})`;
+  }
+  return `${sender} -> ${recipient} handoff`;
+}
+function crossHarnessSummary(details, sender) {
+  const policyRule = optString(details, "policy_rule_id");
+  if (policyRule) {
+    return `${sender} -> operator approval (${policyRule})`;
+  }
+  return `${sender} -> operator approval`;
+}
+var COORDINATION_VIEW_AUDIT_OPS = {
+  VIEW_OPENED: "operator_coordination_view_opened",
+  ENTRY_DRILLED: "operator_handoff_entry_drilled"
+};
+
+// src/coordination/handoff-routes.ts
+var COORDINATION_API_PREFIX = "/api/coordination";
+var COORDINATION_HANDOFFS_PREFIX = "/api/coordination/handoffs";
+var COORDINATION_LIST_DEFAULT_LIMIT = 50;
+var COORDINATION_LIST_MAX_LIMIT = 500;
+var HandoffEventBridge = class {
+  listeners = /* @__PURE__ */ new Set();
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  emit(entry) {
+    for (const listener of this.listeners) {
+      try {
+        listener(entry);
+      } catch {
+      }
+    }
+  }
+};
+function writeJSON6(res, status, payload) {
+  res.writeHead(status, {
+    "Content-Type": "application/json",
+    "Cache-Control": "no-store"
+  });
+  res.end(JSON.stringify(payload));
+}
+function parseLimit4(raw, defaultValue, max) {
+  if (raw === null || raw === "") return defaultValue;
+  const parsed = Number.parseInt(raw, 10);
+  if (Number.isNaN(parsed) || parsed < 0) return defaultValue;
+  return Math.min(parsed, max);
+}
+function matchEntryRoute2(path) {
+  const prefix = `${COORDINATION_HANDOFFS_PREFIX}/`;
+  if (!path.startsWith(prefix)) return null;
+  const rest = path.slice(prefix.length);
+  if (rest.length === 0 || rest === "stream") return null;
+  if (rest.includes("/")) return null;
+  return { entryId: decodeURIComponent(rest) };
+}
+async function handleStream3(deps, res) {
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache, no-transform",
+    Connection: "keep-alive",
+    "X-Accel-Buffering": "no"
+  });
+  const snapshot = await deps.handoffLog.query({ limit: 50 });
+  res.write(
+    `event: handoff_snapshot
+data: ${JSON.stringify({ entries: snapshot })}
+
+`
+  );
+  const unsubscribe = deps.events.subscribe((entry) => {
+    try {
+      res.write(
+        `event: handoff_added
+data: ${JSON.stringify(entry)}
+
+`
+      );
+    } catch {
+    }
+  });
+  const keepAlive = setInterval(() => {
+    try {
+      res.write(": keepalive\n\n");
+    } catch {
+    }
+  }, 25e3);
+  const cleanup = () => {
+    clearInterval(keepAlive);
+    unsubscribe();
+  };
+  res.on("close", cleanup);
+  res.on("error", cleanup);
+}
+async function handleCoordinationRoute(deps, req, res) {
+  const host = req.headers.host || "localhost";
+  const url = new URL(req.url ?? "/", `http://${host}`);
+  const method = (req.method ?? "GET").toUpperCase();
+  const path = url.pathname;
+  if (path !== COORDINATION_API_PREFIX && !path.startsWith(`${COORDINATION_API_PREFIX}/`)) {
+    return false;
+  }
+  const checkAuth = authMiddleware(deps.authConfig);
+  if (!checkAuth(req, res, url)) return true;
+  try {
+    if (method === "GET" && path === `${COORDINATION_HANDOFFS_PREFIX}/stream`) {
+      await handleStream3(deps, res);
+      return true;
+    }
+    if (method === "GET" && path === COORDINATION_HANDOFFS_PREFIX) {
+      const limit = parseLimit4(
+        url.searchParams.get("limit"),
+        COORDINATION_LIST_DEFAULT_LIMIT,
+        COORDINATION_LIST_MAX_LIMIT
+      );
+      const since = url.searchParams.get("since") ?? void 0;
+      const until = url.searchParams.get("until") ?? void 0;
+      const agentId = url.searchParams.get("agent_id") ?? void 0;
+      const entries = await deps.handoffLog.query({
+        limit,
+        ...since !== void 0 ? { since } : {},
+        ...until !== void 0 ? { until } : {},
+        ...agentId !== void 0 ? { agent_id: agentId } : {}
+      });
+      deps.auditLog.append(
+        "l2",
+        COORDINATION_VIEW_AUDIT_OPS.VIEW_OPENED,
+        deps.operatorId,
+        {
+          fortress_id: deps.handoffLog.getFortressId(),
+          result_count: entries.length,
+          ...since !== void 0 ? { since } : {},
+          ...until !== void 0 ? { until } : {},
+          ...agentId !== void 0 ? { agent_id: agentId } : {}
+        }
+      );
+      writeJSON6(res, 200, { ok: true, data: { entries } });
+      return true;
+    }
+    const entryMatch = matchEntryRoute2(path);
+    if (method === "GET" && entryMatch) {
+      const detail = await deps.handoffLog.getEntry(entryMatch.entryId);
+      if (!detail) {
+        writeJSON6(res, 404, { ok: false, error: "not_found" });
+        return true;
+      }
+      deps.auditLog.append(
+        "l2",
+        COORDINATION_VIEW_AUDIT_OPS.ENTRY_DRILLED,
+        deps.operatorId,
+        {
+          fortress_id: deps.handoffLog.getFortressId(),
+          entry_id: detail.entry.entry_id,
+          event_class: detail.entry.event_class,
+          source_agent_id: detail.entry.source_agent_id,
+          target_agent_id: detail.entry.target_agent_id
+        }
+      );
+      writeJSON6(res, 200, { ok: true, data: detail });
+      return true;
+    }
+    writeJSON6(res, 404, { ok: false, error: "not_found", path });
+    return true;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    writeJSON6(res, 500, { ok: false, error: "internal", detail: msg });
+    return true;
+  }
+}
 
 // src/principal-policy/dashboard.ts
 var SESSION_TTL_REMOTE_MS = 5 * 60 * 1e3;
@@ -16645,6 +16945,17 @@ var DashboardApprovalChannel = class {
    * dispatcher's audited paths.
    */
   sentinelDispatcher = null;
+  /**
+   * v1.3 WP-V1.3-3 Omega-1 Coordination Handoff Visualization.
+   * Mounted additively at `/api/coordination/*` when set. Read-only
+   * against the audit log; the only writes are operator-action audit
+   * events (operator_coordination_view_opened,
+   * operator_handoff_entry_drilled).
+   */
+  handoffLog = null;
+  handoffEventBridge = null;
+  handoffAuditLog = null;
+  handoffOperatorId = null;
   constructor(config) {
     this.config = config;
     this.authToken = config.auth_token;
@@ -16712,6 +17023,18 @@ var DashboardApprovalChannel = class {
   setSentinelDispatcher(dispatcher) {
     this.sentinelDispatcher = dispatcher;
   }
+  /**
+   * v1.3 WP-V1.3-3 Omega-1: bind the Coordination handoff log +
+   * event bridge + audit log + operator id. Once set, requests to
+   * `/api/coordination/*` route through `handleCoordinationRoute`.
+   * Pass `null` for any field to detach.
+   */
+  setHandoffLog(opts) {
+    this.handoffLog = opts.handoffLog;
+    this.handoffEventBridge = opts.eventBridge ?? null;
+    this.handoffAuditLog = opts.auditLog ?? null;
+    this.handoffOperatorId = opts.operatorId ?? null;
+  }
   /**
    * v1.3 WP-V1.3-10 dispatch entry point. Called from `handleRequest`
    * before the legacy approval route table. Returns true when served.
@@ -16750,6 +17073,30 @@ var DashboardApprovalChannel = class {
       res
     );
   }
+  /**
+   * v1.3 WP-V1.3-3 Omega-1 dispatch entry point. Routes
+   * `/api/coordination/*` requests through the coordination router
+   * when a HandoffLog has been bound. Returns true when served.
+   */
+  async dispatchCoordination(req, res) {
+    if (!this.handoffLog || !this.handoffEventBridge || !this.handoffAuditLog) {
+      return false;
+    }
+    return handleCoordinationRoute(
+      {
+        authConfig: {
+          loopbackAutoAuth: this._autoAuthLocalhost,
+          ...this.authToken !== void 0 ? { authToken: this.authToken } : {}
+        },
+        handoffLog: this.handoffLog,
+        auditLog: this.handoffAuditLog,
+        operatorId: this.handoffOperatorId ?? this.identityManager?.getPrimaryIdentityId() ?? "operator_dashboard",
+        events: this.handoffEventBridge
+      },
+      req,
+      res
+    );
+  }
   /**
    * v1.1 dispatch entry point. Called from `handleRequest` before the
    * legacy route table. Returns true when the request was served by v1.1
@@ -17149,6 +17496,18 @@ var DashboardApprovalChannel = class {
       });
       return;
     }
+    if (this.handoffLog && url.pathname.startsWith(COORDINATION_API_PREFIX)) {
+      this.dispatchCoordination(req, res).then((handled) => {
+        if (handled) return;
+        this.handleLegacyRequest(req, res, url, method);
+      }).catch(() => {
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ error: "Internal server error" }));
+        }
+      });
+      return;
+    }
     if (this.v11Bindings) {
       this.dispatchV11(req, res, url, method).then((handled) => {
         if (handled) return;
@@ -21344,7 +21703,7 @@ var ALERT_SIGMA2 = 6;
 var BASELINE_WINDOWS2 = 7;
 var QUERY_LIMIT2 = 1e4;
 var MULTI_NEW_PARTNER_ALERT_THRESHOLD = 3;
-var OPERATOR_PSEUDO_AGENT = "operator";
+var OPERATOR_PSEUDO_AGENT2 = "operator";
 var HANDOFF_OP = "v1.1_local_handoff";
 var CROSS_HARNESS_OPS = /* @__PURE__ */ new Set([
   "cross_harness_approval_aggregated",
@@ -21577,7 +21936,7 @@ function extractInterAgentEvents(entries) {
       if (!sender) continue;
       out.push({
         sender,
-        recipient: OPERATOR_PSEUDO_AGENT,
+        recipient: OPERATOR_PSEUDO_AGENT2,
         timestampMs: Date.parse(entry.timestamp),
         auditId: `${entry.timestamp}:${entry.operation}`
       });
@@ -41088,6 +41447,19 @@ ${err.message}
     identityId: aggregatorIdentityId
   });
   anomalyDispatcher.start();
+  const handoffLog = new HandoffLog({
+    auditLog,
+    fortressId: fortressIdForAggregator
+  });
+  const handoffEventBridge = new HandoffEventBridge();
+  if (dashboard) {
+    dashboard.setHandoffLog({
+      handoffLog,
+      eventBridge: handoffEventBridge,
+      auditLog,
+      operatorId: aggregatorIdentityId
+    });
+  }
   const policyTools = createPrincipalPolicyTools(policy, baseline, auditLog);
   const { tools: sanctuaryMetaTools } = createSanctuaryTools({
     config,