scene-capability-engine 3.3.5 → 3.3.10

package/lib/runtime/business-mode-resolver.js

@@ -0,0 +1,240 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs-extra');
+
+const DEFAULT_BUSINESS_MODE_POLICY = 'docs/interactive-customization/business-mode-policy-baseline.json';
+const BUSINESS_MODES = new Set(['user-mode', 'ops-mode', 'dev-mode']);
+
+const BUILTIN_POLICY = Object.freeze({
+  version: '1.0.0',
+  defaults: {
+    mode: null,
+    enforce_alignment: true
+  },
+  modes: {
+    'user-mode': {
+      execution_mode: 'suggestion',
+      dialogue_profile: 'business-user',
+      ui_mode: 'user-app',
+      runtime_mode: 'user-assist',
+      runtime_environment: 'staging',
+      auto_execute_low_risk: false
+    },
+    'ops-mode': {
+      execution_mode: 'apply',
+      dialogue_profile: 'system-maintainer',
+      ui_mode: 'ops-console',
+      runtime_mode: 'ops-fix',
+      runtime_environment: 'staging',
+      auto_execute_low_risk: false
+    },
+    'dev-mode': {
+      execution_mode: 'apply',
+      dialogue_profile: 'system-maintainer',
+      ui_mode: 'ops-console',
+      runtime_mode: 'feature-dev',
+      runtime_environment: 'dev',
+      auto_execute_low_risk: false
+    }
+  }
+});
+
+function normalizeBusinessMode(value) {
+  const normalized = `${value || ''}`.trim().toLowerCase();
+  return normalized || null;
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (value === true || value === false) {
+    return value;
+  }
+  return fallback;
+}
+
+function sanitizeModePreset(rawPreset = {}) {
+  return {
+    execution_mode: `${rawPreset.execution_mode || ''}`.trim().toLowerCase() || null,
+    dialogue_profile: `${rawPreset.dialogue_profile || ''}`.trim().toLowerCase() || null,
+    ui_mode: `${rawPreset.ui_mode || ''}`.trim().toLowerCase() || null,
+    runtime_mode: `${rawPreset.runtime_mode || ''}`.trim().toLowerCase() || null,
+    runtime_environment: `${rawPreset.runtime_environment || ''}`.trim().toLowerCase() || null,
+    auto_execute_low_risk: normalizeBoolean(rawPreset.auto_execute_low_risk, false)
+  };
+}
+
+function normalizePolicy(rawPolicy = {}) {
+  const defaults = rawPolicy && typeof rawPolicy.defaults === 'object' ? rawPolicy.defaults : {};
+  const rawModes = rawPolicy && rawPolicy.modes && typeof rawPolicy.modes === 'object'
+    ? rawPolicy.modes
+    : {};
+
+  const mergedModes = {};
+  for (const [modeKey, fallbackPreset] of Object.entries(BUILTIN_POLICY.modes)) {
+    const overridePreset = rawModes[modeKey] && typeof rawModes[modeKey] === 'object'
+      ? rawModes[modeKey]
+      : null;
+    mergedModes[modeKey] = sanitizeModePreset({
+      ...fallbackPreset,
+      ...(overridePreset || {})
+    });
+  }
+
+  return {
+    version: `${rawPolicy.version || BUILTIN_POLICY.version}`,
+    defaults: {
+      mode: normalizeBusinessMode(defaults.mode),
+      enforce_alignment: normalizeBoolean(defaults.enforce_alignment, BUILTIN_POLICY.defaults.enforce_alignment)
+    },
+    modes: mergedModes
+  };
+}
+
+function loadBusinessModePolicy({ cwd, policyPath }) {
+  const policyRef = `${policyPath || DEFAULT_BUSINESS_MODE_POLICY}`.trim() || DEFAULT_BUSINESS_MODE_POLICY;
+  const resolvedPath = path.isAbsolute(policyRef) ? policyRef : path.resolve(cwd, policyRef);
+
+  if (!fs.existsSync(resolvedPath)) {
+    return {
+      policy: normalizePolicy(BUILTIN_POLICY),
+      policy_path: resolvedPath,
+      policy_source: 'builtin'
+    };
+  }
+
+  try {
+    const rawPolicy = fs.readJsonSync(resolvedPath);
+    return {
+      policy: normalizePolicy(rawPolicy),
+      policy_path: resolvedPath,
+      policy_source: 'file'
+    };
+  } catch (_error) {
+    return {
+      policy: normalizePolicy(BUILTIN_POLICY),
+      policy_path: resolvedPath,
+      policy_source: 'builtin'
+    };
+  }
+}
+
+function inferBusinessMode(options = {}) {
+  const runtimeMode = `${options.runtimeMode || ''}`.trim().toLowerCase();
+  const dialogueProfile = `${options.dialogueProfile || ''}`.trim().toLowerCase();
+  const executionMode = `${options.executionMode || ''}`.trim().toLowerCase();
+
+  if (runtimeMode === 'feature-dev') {
+    return 'dev-mode';
+  }
+  if (dialogueProfile === 'system-maintainer' || executionMode === 'apply') {
+    return 'ops-mode';
+  }
+  return 'user-mode';
+}
+
+function applyPresetDefaults(options = {}, explicitKeys = new Set(), preset = null) {
+  if (!preset) {
+    return;
+  }
+
+  if (!explicitKeys.has('executionMode') && preset.execution_mode) {
+    options.executionMode = preset.execution_mode;
+  }
+  if (!explicitKeys.has('dialogueProfile') && preset.dialogue_profile) {
+    options.dialogueProfile = preset.dialogue_profile;
+  }
+  if (!explicitKeys.has('uiMode') && preset.ui_mode) {
+    options.uiMode = preset.ui_mode;
+  }
+  if (!explicitKeys.has('runtimeMode') && preset.runtime_mode) {
+    options.runtimeMode = preset.runtime_mode;
+  }
+  if (!explicitKeys.has('runtimeEnvironment') && preset.runtime_environment) {
+    options.runtimeEnvironment = preset.runtime_environment;
+  }
+  if (!explicitKeys.has('autoExecuteLowRisk') && typeof preset.auto_execute_low_risk === 'boolean') {
+    options.autoExecuteLowRisk = preset.auto_execute_low_risk;
+  }
+}
+
+function collectPresetConflicts(options = {}, preset = null) {
+  if (!preset) {
+    return [];
+  }
+
+  const checks = [
+    { key: 'execution_mode', actual: `${options.executionMode || ''}`.trim().toLowerCase(), expected: preset.execution_mode },
+    { key: 'dialogue_profile', actual: `${options.dialogueProfile || ''}`.trim().toLowerCase(), expected: preset.dialogue_profile },
+    { key: 'ui_mode', actual: `${options.uiMode || ''}`.trim().toLowerCase(), expected: preset.ui_mode },
+    { key: 'runtime_mode', actual: `${options.runtimeMode || ''}`.trim().toLowerCase(), expected: preset.runtime_mode },
+    { key: 'runtime_environment', actual: `${options.runtimeEnvironment || ''}`.trim().toLowerCase(), expected: preset.runtime_environment }
+  ];
+
+  return checks
+    .filter(item => item.expected && item.actual !== item.expected)
+    .map(item => ({
+      key: item.key,
+      expected: item.expected,
+      actual: item.actual || '(empty)'
+    }));
+}
+
+function buildAlignmentError(mode, conflicts = []) {
+  const summary = conflicts
+    .map(item => `${item.key}: expected ${item.expected}, got ${item.actual}`)
+    .join('; ');
+  return `--business-mode ${mode} conflicts with explicit options (${summary}). Use --allow-mode-override to continue.`;
+}
+
+function applyBusinessModePolicy(options = {}, explicitKeys = new Set(), cwd = process.cwd()) {
+  const policyInfo = loadBusinessModePolicy({
+    cwd,
+    policyPath: options.businessModePolicy || DEFAULT_BUSINESS_MODE_POLICY
+  });
+
+  const normalizedInputMode = normalizeBusinessMode(options.businessMode);
+  const fallbackMode = policyInfo.policy.defaults.mode && BUSINESS_MODES.has(policyInfo.policy.defaults.mode)
+    ? policyInfo.policy.defaults.mode
+    : null;
+  const resolvedMode = normalizedInputMode || fallbackMode || inferBusinessMode(options);
+  const preset = policyInfo.policy.modes[resolvedMode] || null;
+  const modeExplicitlyProvided = normalizedInputMode != null;
+  const allowModeOverride = options.allowModeOverride === true;
+  const enforceAlignment = policyInfo.policy.defaults.enforce_alignment === true;
+
+  if (modeExplicitlyProvided) {
+    applyPresetDefaults(options, explicitKeys, preset);
+  }
+
+  const conflicts = modeExplicitlyProvided ? collectPresetConflicts(options, preset) : [];
+  if (modeExplicitlyProvided && enforceAlignment && !allowModeOverride && conflicts.length > 0) {
+    throw new Error(buildAlignmentError(resolvedMode, conflicts));
+  }
+
+  options.businessMode = resolvedMode;
+  options.businessModePolicy = options.businessModePolicy || DEFAULT_BUSINESS_MODE_POLICY;
+
+  return {
+    business_mode: resolvedMode,
+    mode_explicit: modeExplicitlyProvided,
+    allow_mode_override: allowModeOverride,
+    policy_path: policyInfo.policy_path,
+    policy_source: policyInfo.policy_source,
+    preset,
+    conflicts
+  };
+}
+
+module.exports = {
+  DEFAULT_BUSINESS_MODE_POLICY,
+  BUSINESS_MODES,
+  BUILTIN_POLICY,
+  normalizeBusinessMode,
+  normalizePolicy,
+  loadBusinessModePolicy,
+  inferBusinessMode,
+  applyPresetDefaults,
+  collectPresetConflicts,
+  buildAlignmentError,
+  applyBusinessModePolicy
+};

package/lib/runtime/session-store.js

@@ -0,0 +1,207 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { SteeringContract, normalizeToolName } = require('./steering-contract');
+
+const SESSION_SCHEMA_VERSION = '1.0';
+const SESSION_DIR = path.join('.sce', 'sessions');
+
+function toRelativePosix(workspaceRoot, absolutePath) {
+  return path.relative(workspaceRoot, absolutePath).replace(/\\/g, '/');
+}
+
+function safeSessionId(value) {
+  return `${value || ''}`.trim().replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+function generateSessionId() {
+  const now = new Date();
+  const yyyy = now.getUTCFullYear();
+  const mm = `${now.getUTCMonth() + 1}`.padStart(2, '0');
+  const dd = `${now.getUTCDate()}`.padStart(2, '0');
+  const hh = `${now.getUTCHours()}`.padStart(2, '0');
+  const mi = `${now.getUTCMinutes()}`.padStart(2, '0');
+  const ss = `${now.getUTCSeconds()}`.padStart(2, '0');
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `sess-${yyyy}${mm}${dd}-${hh}${mi}${ss}-${rand}`;
+}
+
+class SessionStore {
+  constructor(workspaceRoot, steeringContract = null) {
+    this._workspaceRoot = workspaceRoot;
+    this._sessionsDir = path.join(workspaceRoot, SESSION_DIR);
+    this._steeringContract = steeringContract || new SteeringContract(workspaceRoot);
+  }
+
+  async startSession(options = {}) {
+    const tool = normalizeToolName(options.tool || 'generic');
+    const agentVersion = options.agentVersion ? `${options.agentVersion}` : null;
+    const objective = `${options.objective || ''}`.trim();
+    const requestedId = safeSessionId(options.sessionId);
+    const sessionId = requestedId || generateSessionId();
+    const now = new Date().toISOString();
+
+    await this._steeringContract.ensureContract();
+    const steeringPayload = await this._steeringContract.buildCompilePayload(tool, agentVersion);
+    await fs.ensureDir(this._sessionsDir);
+
+    const sessionPath = this._sessionPath(sessionId);
+    if (await fs.pathExists(sessionPath)) {
+      throw new Error(`Session already exists: ${sessionId}`);
+    }
+
+    const session = {
+      schema_version: SESSION_SCHEMA_VERSION,
+      session_id: sessionId,
+      tool,
+      agent_version: agentVersion,
+      objective,
+      status: 'active',
+      started_at: now,
+      updated_at: now,
+      workspace: {
+        root: this._workspaceRoot,
+      },
+      steering: {
+        manifest_path: toRelativePosix(this._workspaceRoot, this._steeringContract.manifestPath),
+        source_mode: steeringPayload.source_mode,
+        compatibility: steeringPayload.compatibility,
+      },
+      snapshots: [],
+      timeline: [
+        {
+          at: now,
+          event: 'session_started',
+          detail: {
+            tool,
+            agent_version: agentVersion,
+            objective,
+          },
+        },
+      ],
+    };
+
+    await this._writeSession(sessionId, session);
+    return session;
+  }
+
+  async resumeSession(sessionRef = 'latest', options = {}) {
+    const { sessionId, session } = await this._resolveSession(sessionRef);
+    const now = new Date().toISOString();
+    const status = `${options.status || 'active'}`.trim() || 'active';
+
+    session.status = status;
+    session.updated_at = now;
+    session.timeline = Array.isArray(session.timeline) ? session.timeline : [];
+    session.timeline.push({
+      at: now,
+      event: 'session_resumed',
+      detail: { status },
+    });
+
+    await this._writeSession(sessionId, session);
+    return session;
+  }
+
+  async snapshotSession(sessionRef = 'latest', options = {}) {
+    const { sessionId, session } = await this._resolveSession(sessionRef);
+    const now = new Date().toISOString();
+    const summary = `${options.summary || ''}`.trim();
+    const status = options.status ? `${options.status}`.trim() : session.status;
+    const payload = options.payload == null ? null : options.payload;
+
+    session.snapshots = Array.isArray(session.snapshots) ? session.snapshots : [];
+    session.timeline = Array.isArray(session.timeline) ? session.timeline : [];
+
+    const snapshot = {
+      snapshot_id: `snap-${session.snapshots.length + 1}`,
+      captured_at: now,
+      status,
+      summary,
+      payload,
+    };
+
+    session.snapshots.push(snapshot);
+    session.status = status;
+    session.updated_at = now;
+    session.timeline.push({
+      at: now,
+      event: 'snapshot_created',
+      detail: {
+        snapshot_id: snapshot.snapshot_id,
+        status,
+      },
+    });
+
+    await this._writeSession(sessionId, session);
+    return session;
+  }
+
+  async getSession(sessionRef = 'latest') {
+    const resolved = await this._resolveSession(sessionRef);
+    return resolved.session;
+  }
+
+  async listSessions() {
+    if (!await fs.pathExists(this._sessionsDir)) {
+      return [];
+    }
+    const entries = await fs.readdir(this._sessionsDir);
+    const records = [];
+    for (const entry of entries) {
+      if (!entry.endsWith('.json')) {
+        continue;
+      }
+      const sessionId = entry.slice(0, -'.json'.length);
+      try {
+        const session = await fs.readJson(this._sessionPath(sessionId));
+        records.push(session);
+      } catch (_error) {
+        // Ignore unreadable entries.
+      }
+    }
+    records.sort((a, b) => {
+      const left = Date.parse(a.updated_at || a.started_at || 0);
+      const right = Date.parse(b.updated_at || b.started_at || 0);
+      return right - left;
+    });
+    return records;
+  }
+
+  async _resolveSession(sessionRef) {
+    const ref = `${sessionRef || 'latest'}`.trim();
+    if (ref === 'latest') {
+      const sessions = await this.listSessions();
+      if (sessions.length === 0) {
+        throw new Error('No session found');
+      }
+      const session = sessions[0];
+      return { sessionId: session.session_id, session };
+    }
+
+    const sessionId = safeSessionId(ref);
+    if (!sessionId) {
+      throw new Error(`Invalid session id: ${ref}`);
+    }
+    const sessionPath = this._sessionPath(sessionId);
+    if (!await fs.pathExists(sessionPath)) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+    const session = await fs.readJson(sessionPath);
+    return { sessionId, session };
+  }
+
+  async _writeSession(sessionId, session) {
+    await fs.ensureDir(this._sessionsDir);
+    await fs.writeJson(this._sessionPath(sessionId), session, { spaces: 2 });
+  }
+
+  _sessionPath(sessionId) {
+    return path.join(this._sessionsDir, `${sessionId}.json`);
+  }
+}
+
+module.exports = {
+  SessionStore,
+  SESSION_SCHEMA_VERSION,
+  SESSION_DIR,
+};