@neuroverseos/governance 0.4.3 → 0.5.1

package/dist/{build-EGBGZFIJ.js → build-THUEYMVT.js}

@@ -2,19 +2,19 @@ import {
   DeriveInputError,
   DeriveProviderError,
   deriveWorld
-} from "./chunk-FHXXD2TI.js";
+} from "./chunk-QZ666FCV.js";
 import {
   DERIVE_EXIT_CODES
 } from "./chunk-FMSTRBBS.js";
-import "./chunk-INWQHLPS.js";
 import "./chunk-OT6PXH54.js";
+import "./chunk-INWQHLPS.js";
 import "./chunk-7P3S7MAY.js";
-import {
-  emitWorldDefinition
-} from "./chunk-YPCVY4GS.js";
 import {
   parseWorldMarkdown
 } from "./chunk-3NZMMSOW.js";
+import {
+  emitWorldDefinition
+} from "./chunk-YPCVY4GS.js";
 import "./chunk-QWGCMQQD.js";
 
 // src/cli/build.ts

package/dist/{chunk-YJ34R5NB.js → chunk-5RAQ5DZW.js}

@@ -4,12 +4,12 @@ import {
   extractScope,
   trackPlanProgress
 } from "./chunk-5U2MQO5P.js";
+import {
+  loadWorld
+} from "./chunk-EQUAWNXW.js";
 import {
   evaluateGuard
 } from "./chunk-ZAF6JH23.js";
-import {
-  loadWorld
-} from "./chunk-I4RTIMLX.js";
 
 // src/engine/tool-classifier.ts
 var TOOL_CATEGORY_MAP = {

package/dist/{chunk-RDA7ISWC.js → chunk-6UPEUMJ2.js}

@@ -1,9 +1,9 @@
+import {
+  loadWorld
+} from "./chunk-EQUAWNXW.js";
 import {
   evaluateGuard
 } from "./chunk-ZAF6JH23.js";
-import {
-  loadWorld
-} from "./chunk-I4RTIMLX.js";
 
 // src/adapters/express.ts
 function methodToCategory(method) {

package/dist/chunk-7UU7V3AD.js

@@ -0,0 +1,447 @@
+import {
+  MENTRA_KNOWN_INTENTS,
+  getMentraIntent,
+  isAIIntent
+} from "./chunk-GJ6LM4JZ.js";
+import {
+  buildEngineOptions,
+  trackPlanProgress
+} from "./chunk-5U2MQO5P.js";
+import {
+  loadWorld
+} from "./chunk-EQUAWNXW.js";
+import {
+  evaluateGuard
+} from "./chunk-ZAF6JH23.js";
+
+// src/adapters/mentraos.ts
+var DEFAULT_USER_RULES = {
+  aiDataPolicy: "declared_only",
+  aiActionPolicy: "confirm_all",
+  aiPurchasePolicy: "confirm_each",
+  aiMessagingPolicy: "confirm_each",
+  dataRetentionPolicy: "app_declared",
+  maxAIProviders: 5
+};
+function evaluateUserRules(intent, rules, appContext) {
+  const def = getMentraIntent(intent);
+  if (!def) return null;
+  if (def.domain === "ai_data" && intent !== "ai_retain_session_data") {
+    if (rules.aiDataPolicy === "block_all") {
+      return {
+        verdict: {
+          status: "BLOCK",
+          ruleId: "user-rule-ai-data-block",
+          reason: `User rules block all AI data sends. Intent: ${intent}`,
+          evidence: makeEvidence("user-rule-ai-data-block")
+        },
+        reason: "User has blocked all AI data sends"
+      };
+    }
+    if (rules.aiDataPolicy === "confirm_each") {
+      return {
+        verdict: {
+          status: "PAUSE",
+          ruleId: "user-rule-ai-data-confirm",
+          reason: `User rules require confirmation for every AI data send. Intent: ${intent}`,
+          evidence: makeEvidence("user-rule-ai-data-confirm")
+        },
+        reason: "User requires confirmation for each AI data send"
+      };
+    }
+    if (!appContext.aiProviderDeclared) {
+      return {
+        verdict: {
+          status: "BLOCK",
+          ruleId: "user-rule-undeclared-provider",
+          reason: `App "${appContext.appId}" has not declared its AI provider. User rules require declared providers only.`,
+          evidence: makeEvidence("user-rule-undeclared-provider")
+        },
+        reason: "App has not declared its AI provider"
+      };
+    }
+  }
+  if (intent === "ai_retain_session_data") {
+    if (rules.dataRetentionPolicy === "never") {
+      return {
+        verdict: {
+          status: "BLOCK",
+          ruleId: "user-rule-no-retention",
+          reason: `User rules block all data retention. App "${appContext.appId}" cannot retain session data.`,
+          evidence: makeEvidence("user-rule-no-retention")
+        },
+        reason: "User has blocked all data retention"
+      };
+    }
+    if (!appContext.dataRetentionOptedIn) {
+      return {
+        verdict: {
+          status: "BLOCK",
+          ruleId: "user-rule-retention-no-optin",
+          reason: `User has not opted in to data retention for app "${appContext.appId}".`,
+          evidence: makeEvidence("user-rule-retention-no-optin")
+        },
+        reason: "User has not opted in to data retention for this app"
+      };
+    }
+  }
+  if (intent === "ai_auto_purchase") {
+    if (rules.aiPurchasePolicy === "block_all") {
+      return {
+        verdict: {
+          status: "BLOCK",
+          ruleId: "user-rule-no-purchases",
+          reason: "User rules block all AI-initiated purchases.",
+          evidence: makeEvidence("user-rule-no-purchases")
+        },
+        reason: "User has blocked all AI purchases"
+      };
+    }
+    return {
+      verdict: {
+        status: "PAUSE",
+        ruleId: "user-rule-purchase-confirm",
+        reason: `AI wants to make a purchase. User rules require per-transaction confirmation.`,
+        evidence: makeEvidence("user-rule-purchase-confirm")
+      },
+      reason: "User requires per-transaction confirmation for AI purchases"
+    };
+  }
+  if (intent === "ai_auto_respond_message") {
+    if (rules.aiMessagingPolicy === "block_all") {
+      return {
+        verdict: {
+          status: "BLOCK",
+          ruleId: "user-rule-no-messaging",
+          reason: "User rules block all AI-initiated messaging.",
+          evidence: makeEvidence("user-rule-no-messaging")
+        },
+        reason: "User has blocked all AI messaging"
+      };
+    }
+    return {
+      verdict: {
+        status: "PAUSE",
+        ruleId: "user-rule-message-confirm",
+        reason: `AI wants to send a message on your behalf. User rules require per-message confirmation.`,
+        evidence: makeEvidence("user-rule-message-confirm")
+      },
+      reason: "User requires per-message confirmation for AI messaging"
+    };
+  }
+  if (def.domain === "ai_action" && intent !== "ai_auto_purchase" && intent !== "ai_auto_respond_message") {
+    if (rules.aiActionPolicy === "block_all") {
+      return {
+        verdict: {
+          status: "BLOCK",
+          ruleId: "user-rule-no-ai-actions",
+          reason: `User rules block all AI auto-actions. Intent: ${intent}`,
+          evidence: makeEvidence("user-rule-no-ai-actions")
+        },
+        reason: "User has blocked all AI auto-actions"
+      };
+    }
+    if (rules.aiActionPolicy === "confirm_all") {
+      return {
+        verdict: {
+          status: "PAUSE",
+          ruleId: "user-rule-action-confirm",
+          reason: `AI wants to take action: ${intent}. User rules require confirmation.`,
+          evidence: makeEvidence("user-rule-action-confirm")
+        },
+        reason: "User requires confirmation for all AI actions"
+      };
+    }
+    if (def.base_risk === "high" || def.base_risk === "critical") {
+      return {
+        verdict: {
+          status: "PAUSE",
+          ruleId: "user-rule-high-risk-confirm",
+          reason: `AI wants to take high-risk action: ${intent}. User rules require confirmation for high-risk actions.`,
+          evidence: makeEvidence("user-rule-high-risk-confirm")
+        },
+        reason: "User requires confirmation for high-risk AI actions"
+      };
+    }
+  }
+  if (intent === "ai_share_with_third_party") {
+    return {
+      verdict: {
+        status: "PAUSE",
+        ruleId: "user-rule-third-party-confirm",
+        reason: `App wants to share your data with a third party beyond its declared AI provider. Confirmation required.`,
+        evidence: makeEvidence("user-rule-third-party-confirm")
+      },
+      reason: "Third-party data sharing requires user confirmation"
+    };
+  }
+  return null;
+}
+function makeEvidence(ruleId) {
+  return {
+    worldId: "mentraos-user-rules",
+    worldName: "MentraOS User Rules",
+    worldVersion: "1.0.0",
+    evaluatedAt: Date.now(),
+    invariantsSatisfied: 0,
+    invariantsTotal: 0,
+    guardsMatched: [ruleId],
+    rulesMatched: [],
+    enforcementLevel: "strict"
+  };
+}
+var MentraGovernedExecutor = class {
+  world;
+  engineOptions;
+  options;
+  planState;
+  planCallbacks;
+  _userRules;
+  _emergencyOverride = false;
+  _emergencyActivatedAt = null;
+  _spatialSession = null;
+  constructor(world, options = {}, userRules = DEFAULT_USER_RULES) {
+    this.world = world;
+    this.options = options;
+    this._userRules = userRules;
+    this.engineOptions = buildEngineOptions(options, options.plan);
+    this.planState = { activePlan: options.plan, engineOptions: this.engineOptions };
+    this.planCallbacks = {
+      onPlanProgress: options.onPlanProgress,
+      onPlanComplete: options.onPlanComplete
+    };
+  }
+  /** Get the current user rules */
+  get userRules() {
+    return this._userRules;
+  }
+  /** Update user rules at runtime (e.g., user changes preferences in phone app) */
+  updateUserRules(rules) {
+    this._userRules = { ...this._userRules, ...rules };
+  }
+  /**
+   * Activate emergency override — user is king.
+   *
+   * Bypasses all NeuroVerse governance rules (user rules, platform rules).
+   * Does NOT bypass MentraOS platform constraints (hardware capability,
+   * declared permissions, session isolation). You can't override physics.
+   *
+   * Returns the timestamp of activation for audit trail.
+   */
+  activateEmergencyOverride() {
+    this._emergencyOverride = true;
+    this._emergencyActivatedAt = Date.now();
+    this.engineOptions = { ...this.engineOptions, emergencyOverride: true };
+    return this._emergencyActivatedAt;
+  }
+  /**
+   * Deactivate emergency override — governance resumes.
+   * Returns the duration the override was active (ms).
+   */
+  deactivateEmergencyOverride() {
+    if (!this._emergencyOverride || !this._emergencyActivatedAt) {
+      return 0;
+    }
+    const duration = Date.now() - this._emergencyActivatedAt;
+    this._emergencyOverride = false;
+    this._emergencyActivatedAt = null;
+    this.engineOptions = { ...this.engineOptions, emergencyOverride: false };
+    return duration;
+  }
+  /** Whether emergency override is currently active */
+  get isEmergencyOverrideActive() {
+    return this._emergencyOverride;
+  }
+  /** Timestamp when emergency override was activated, or null */
+  get emergencyActivatedAt() {
+    return this._emergencyActivatedAt;
+  }
+  // ── Spatial Governance (optional) ────────────────────────────────────────
+  /**
+   * Attach a spatial session to this executor.
+   *
+   * When attached, intents are evaluated against the spatial context
+   * (zone rules + handshake rules) AFTER user rules but BEFORE
+   * hardware and platform checks. This is Layer 1.5.
+   *
+   * Pass null to detach (e.g., when leaving a zone).
+   */
+  setSpatialSession(session) {
+    this._spatialSession = session;
+  }
+  /** Whether a spatial session is currently active */
+  get hasSpatialSession() {
+    return this._spatialSession !== null;
+  }
+  /** Get the current spatial session description */
+  get spatialDescription() {
+    return this._spatialSession?.description ?? null;
+  }
+  /**
+   * Evaluate an intent against user rules + platform world.
+   *
+   * Three-layer evaluation:
+   *   0. Emergency override — if active, skip governance (layers 1 + 1.5 + 3),
+   *      but STILL enforce platform constraints (layer 2)
+   *   1. User rules check — personal governance override, can BLOCK or PAUSE
+   *   1.5. Spatial governance — zone + handshake rules (optional, temporary)
+   *      ↑ ONLY ACTIVE when a spatial session is attached
+   *   2. Hardware capability check — validates glasses support
+   *      ↑ THIS IS A PLATFORM CONSTRAINT — never overridden
+   *   3. Platform guard engine — full world rule evaluation
+   */
+  evaluate(intent, appContext) {
+    const intentDef = getMentraIntent(intent);
+    const glassesModel = appContext.glassesModel;
+    if (!this._emergencyOverride) {
+      const userRulesResult = evaluateUserRules(intent, this._userRules, appContext);
+      if (userRulesResult) {
+        const allowed2 = false;
+        const requiresConfirmation2 = userRulesResult.verdict.status === "PAUSE";
+        const result2 = {
+          allowed: requiresConfirmation2 ? false : false,
+          requiresConfirmation: requiresConfirmation2,
+          verdict: userRulesResult.verdict,
+          intentDef,
+          userRulesResult: { reason: userRulesResult.reason },
+          appContext,
+          decidingLayer: "user_rules"
+        };
+        if (requiresConfirmation2) {
+          this.options.onPause?.(result2);
+        } else {
+          this.options.onBlock?.(result2);
+        }
+        this.options.onEvaluate?.(result2);
+        return result2;
+      }
+    }
+    if (!this._emergencyOverride && this._spatialSession) {
+      const spatialResult = this._spatialSession.evaluate(intent);
+      if (!spatialResult.allowed && !spatialResult.requiresConfirmation) {
+        const verdict2 = {
+          status: "BLOCK",
+          ruleId: "spatial-zone-rule",
+          reason: spatialResult.reason,
+          evidence: makeEvidence("spatial-zone-rule")
+        };
+        const result2 = {
+          allowed: false,
+          requiresConfirmation: false,
+          verdict: verdict2,
+          intentDef,
+          appContext,
+          decidingLayer: "spatial"
+        };
+        this.options.onBlock?.(result2);
+        this.options.onEvaluate?.(result2);
+        return result2;
+      }
+      if (spatialResult.requiresConfirmation) {
+        const verdict2 = {
+          status: "PAUSE",
+          ruleId: "spatial-zone-rule",
+          reason: spatialResult.reason,
+          evidence: makeEvidence("spatial-zone-rule")
+        };
+        const result2 = {
+          allowed: false,
+          requiresConfirmation: true,
+          verdict: verdict2,
+          intentDef,
+          appContext,
+          decidingLayer: "spatial"
+        };
+        this.options.onPause?.(result2);
+        this.options.onEvaluate?.(result2);
+        return result2;
+      }
+    }
+    if (intentDef && glassesModel && !intentDef.supported_glasses.includes(glassesModel)) {
+      const verdict2 = {
+        status: "BLOCK",
+        ruleId: "hardware-capability",
+        reason: `${intent} not supported on ${glassesModel} \u2014 requires: ${intentDef.supported_glasses.join(", ")}`,
+        evidence: {
+          worldId: this.world.world?.world_id ?? "unknown",
+          worldName: this.world.world?.name ?? "unknown",
+          worldVersion: this.world.world?.version ?? "unknown",
+          evaluatedAt: Date.now(),
+          invariantsSatisfied: 0,
+          invariantsTotal: 0,
+          guardsMatched: ["hardware-capability"],
+          rulesMatched: [],
+          enforcementLevel: "strict"
+        }
+      };
+      const result2 = {
+        allowed: false,
+        requiresConfirmation: false,
+        verdict: verdict2,
+        intentDef,
+        appContext,
+        decidingLayer: "hardware"
+      };
+      this.options.onBlock?.(result2);
+      this.options.onEvaluate?.(result2);
+      return result2;
+    }
+    const event = {
+      intent,
+      tool: intentDef?.sdk_method ?? intent,
+      scope: intentDef?.domain ?? "unknown",
+      actionCategory: intentDef?.action_category,
+      riskLevel: intentDef?.base_risk ?? "medium",
+      irreversible: intentDef ? !intentDef.reversible : false,
+      args: {
+        app_id: appContext.appId,
+        ai_provider_declared: appContext.aiProviderDeclared ? 1 : 0,
+        ai_data_types_sent: appContext.aiDataTypesSent,
+        ai_retention_opted_in: appContext.dataRetentionOptedIn ? 1 : 0,
+        glasses_model: glassesModel ?? "unknown",
+        is_ai_intent: isAIIntent(intent) ? 1 : 0
+      }
+    };
+    const verdict = evaluateGuard(event, this.world, this.engineOptions);
+    const allowed = verdict.status === "ALLOW" || verdict.status === "REWARD";
+    const requiresConfirmation = verdict.status === "PAUSE";
+    if (allowed) {
+      trackPlanProgress(event, this.planState, this.planCallbacks);
+    }
+    const result = {
+      allowed,
+      requiresConfirmation,
+      verdict,
+      intentDef,
+      appContext,
+      decidingLayer: this._emergencyOverride ? "emergency_override" : "platform"
+    };
+    if (!allowed && !requiresConfirmation) {
+      this.options.onBlock?.(result);
+    }
+    if (requiresConfirmation) {
+      this.options.onPause?.(result);
+    }
+    this.options.onEvaluate?.(result);
+    return result;
+  }
+  /** Get all known intents for this adapter */
+  get knownIntents() {
+    return MENTRA_KNOWN_INTENTS;
+  }
+};
+async function createMentraGovernedExecutor(worldPath, options = {}, userRules = DEFAULT_USER_RULES) {
+  const world = await loadWorld(worldPath);
+  return new MentraGovernedExecutor(world, options, userRules);
+}
+function createMentraGovernedExecutorFromWorld(world, options = {}, userRules = DEFAULT_USER_RULES) {
+  return new MentraGovernedExecutor(world, options, userRules);
+}
+
+export {
+  DEFAULT_USER_RULES,
+  evaluateUserRules,
+  MentraGovernedExecutor,
+  createMentraGovernedExecutor,
+  createMentraGovernedExecutorFromWorld
+};

package/dist/{chunk-ZEIT2QLM.js → chunk-EK77AJAH.js}

@@ -4,12 +4,12 @@ import {
   createAgentState,
   tickAgentStates
 } from "./chunk-D2UCV5AK.js";
+import {
+  loadWorld
+} from "./chunk-EQUAWNXW.js";
 import {
   evaluateGuard
 } from "./chunk-ZAF6JH23.js";
-import {
-  loadWorld
-} from "./chunk-I4RTIMLX.js";
 import {
   advancePlan,
   evaluatePlan,
@@ -20,7 +20,9 @@ import {
 async function defaultToolExecutor(name, args) {
   return `Tool "${name}" executed successfully with args: ${JSON.stringify(args)}`;
 }
-var SessionManager = class {
+var SessionManager = class _SessionManager {
+  /** Maximum unique agent IDs tracked before eviction. Prevents unbounded memory growth. */
+  static MAX_AGENTS = 1e4;
   config;
   state;
   engineOptions;
@@ -84,6 +86,16 @@ var SessionManager = class {
       if (verdict.status === "REWARD" && verdict.reward) {
         agentState = applyReward(agentState, verdict.reward, verdict.ruleId ?? "unknown");
       }
+      if (this.state.agentStates.size >= _SessionManager.MAX_AGENTS && !this.state.agentStates.has(event.roleId)) {
+        const oldest = this.state.agentStates.keys().next().value;
+        if (oldest !== void 0) {
+          this.state.agentStates.delete(oldest);
+        }
+        process.stderr.write(
+          `[neuroverse] Warning: agent state map at capacity (${_SessionManager.MAX_AGENTS}), evicted oldest entry
+`
+        );
+      }
       this.state.agentStates.set(event.roleId, agentState);
     }
     this.config.onVerdict?.(verdict, event);
@@ -194,11 +206,17 @@ async function runPipeMode(config) {
     process.stderr.write(`[neuroverse] Plan: ${state.plan.plan_id} (${state.plan.objective})
 `);
   }
+  const MAX_BUFFER_SIZE = 1e6;
   return new Promise((resolve, reject) => {
     let buffer = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
       buffer += chunk;
+      if (buffer.length > MAX_BUFFER_SIZE) {
+        process.stderr.write("[neuroverse] Warning: pipe buffer exceeded 1MB, resetting\n");
+        buffer = "";
+        return;
+      }
       const lines = buffer.split("\n");
       buffer = lines.pop() ?? "";
       for (const line of lines) {

package/dist/{chunk-3S5AD4AB.js → chunk-FGOSKQDE.js}

@@ -3,12 +3,12 @@ import {
   buildEngineOptions,
   trackPlanProgress
 } from "./chunk-5U2MQO5P.js";
+import {
+  loadWorld
+} from "./chunk-EQUAWNXW.js";
 import {
   evaluateGuard
 } from "./chunk-ZAF6JH23.js";
-import {
-  loadWorld
-} from "./chunk-I4RTIMLX.js";
 
 // src/adapters/github.ts
 var GitHubGovernanceBlockedError = class extends GovernanceBlockedError {