@yemi33/minions 0.1.2420 → 0.1.2422

package/docs/demo/memory-system.js

@@ -0,0 +1,208 @@
+(function attachMemoryExplainer(globalObject, factory) {
+  const api = factory();
+
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = api;
+  }
+  if (globalObject) {
+    globalObject.MemoryExplainer = api;
+  }
+
+  if (typeof document !== 'undefined') {
+    const start = () => api.init(document);
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', start, { once: true });
+    } else {
+      start();
+    }
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : this, function memoryExplainerFactory() {
+  'use strict';
+
+  const FORWARD_KEYS = new Set(['ArrowRight', 'ArrowDown', 'next']);
+  const BACKWARD_KEYS = new Set(['ArrowLeft', 'ArrowUp', 'previous']);
+
+  function createSelectionModel(inputIds, initialId) {
+    if (!Array.isArray(inputIds) || inputIds.length === 0) {
+      throw new TypeError('Selection model requires at least one item');
+    }
+    const ids = inputIds.map(id => String(id || '').trim());
+    if (ids.some(id => !id)) {
+      throw new TypeError('Selection model ids must be non-empty');
+    }
+    if (new Set(ids).size !== ids.length) {
+      throw new TypeError('Selection model ids must be unique');
+    }
+
+    let index = ids.indexOf(String(initialId || ''));
+    if (index < 0) index = 0;
+
+    function current() {
+      return ids[index];
+    }
+
+    function select(id) {
+      const nextIndex = ids.indexOf(String(id || ''));
+      if (nextIndex >= 0) index = nextIndex;
+      return current();
+    }
+
+    function move(action) {
+      if (FORWARD_KEYS.has(action)) {
+        index = (index + 1) % ids.length;
+      } else if (BACKWARD_KEYS.has(action)) {
+        index = (index - 1 + ids.length) % ids.length;
+      } else if (action === 'Home') {
+        index = 0;
+      } else if (action === 'End') {
+        index = ids.length - 1;
+      }
+      return current();
+    }
+
+    return { current, select, move };
+  }
+
+  function setupSelectionGroup(root, options) {
+    if (!root) return null;
+    const items = Array.from(root.querySelectorAll(options.itemSelector));
+    if (!items.length) return null;
+    const ids = items.map(item => item.dataset[options.dataKey]);
+    const initial = ids.find((id, index) => options.isInitiallySelected(items[index])) || ids[0];
+    const model = createSelectionModel(ids, initial);
+    const panels = Array.from(root.querySelectorAll(options.panelSelector));
+
+    function render(id, focusItem) {
+      items.forEach(item => {
+        const selected = item.dataset[options.dataKey] === id;
+        item.setAttribute(options.selectedAttribute, String(selected));
+        item.tabIndex = selected ? 0 : -1;
+        item.classList.toggle('is-active', selected);
+        if (selected && focusItem) item.focus();
+      });
+      panels.forEach(panel => {
+        const selected = panel.id === options.panelId(id);
+        panel.hidden = !selected;
+        panel.classList.toggle('is-active', selected);
+      });
+      if (typeof options.onRender === 'function') options.onRender(id, ids.indexOf(id), ids.length);
+      return id;
+    }
+
+    items.forEach(item => {
+      item.addEventListener('click', () => render(model.select(item.dataset[options.dataKey]), false));
+      item.addEventListener('keydown', event => {
+        if (!FORWARD_KEYS.has(event.key)
+          && !BACKWARD_KEYS.has(event.key)
+          && event.key !== 'Home'
+          && event.key !== 'End') return;
+        event.preventDefault();
+        render(model.move(event.key), true);
+      });
+    });
+
+    render(model.current(), false);
+    return {
+      current: model.current,
+      select(id, focusItem) {
+        return render(model.select(id), !!focusItem);
+      },
+      move(action, focusItem) {
+        return render(model.move(action), !!focusItem);
+      },
+    };
+  }
+
+  function initJourney(doc) {
+    const root = doc.getElementById('memory-journey');
+    const shell = root && root.querySelector('.journey-shell');
+    if (!root || !shell) return null;
+    const liveRegion = root.querySelector('[data-journey-status]');
+    const controller = setupSelectionGroup(root, {
+      itemSelector: '[data-step-id]',
+      panelSelector: '.journey-panel',
+      dataKey: 'stepId',
+      selectedAttribute: 'aria-selected',
+      panelId: id => `journey-${id}`,
+      isInitiallySelected: item => item.getAttribute('aria-selected') === 'true',
+      onRender(id, index, count) {
+        const progress = count > 1 ? (index * 100) / (count - 1) : 0;
+        shell.style.setProperty('--journey-progress', `${progress}%`);
+        if (liveRegion) {
+          const label = root.querySelector(`[data-step-id="${id}"] .step-label`);
+          liveRegion.textContent = `Showing step ${index + 1} of 7: ${label ? label.textContent : id}`;
+        }
+      },
+    });
+    if (!controller) return null;
+
+    const playButton = root.querySelector('[data-play-journey]');
+    const reducedMotion = typeof matchMedia === 'function'
+      && matchMedia('(prefers-reduced-motion: reduce)').matches;
+    let timer = null;
+
+    function stop() {
+      if (timer) clearInterval(timer);
+      timer = null;
+      shell.classList.remove('is-playing');
+      if (playButton) {
+        playButton.setAttribute('aria-pressed', 'false');
+        playButton.querySelector('span').textContent = 'Play the flow';
+      }
+    }
+
+    function advance() {
+      controller.move('next', false);
+    }
+
+    if (playButton) {
+      playButton.addEventListener('click', () => {
+        if (reducedMotion) {
+          advance();
+          return;
+        }
+        if (timer) {
+          stop();
+          return;
+        }
+        advance();
+        shell.classList.add('is-playing');
+        playButton.setAttribute('aria-pressed', 'true');
+        playButton.querySelector('span').textContent = 'Pause the flow';
+        timer = setInterval(advance, 3200);
+      });
+    }
+
+    doc.addEventListener('visibilitychange', () => {
+      if (doc.hidden) stop();
+    });
+    return controller;
+  }
+
+  function initArchitectureMap(doc) {
+    const root = doc.getElementById('architecture-map');
+    return setupSelectionGroup(root, {
+      itemSelector: '[data-map-node]',
+      panelSelector: '.map-detail',
+      dataKey: 'mapNode',
+      selectedAttribute: 'aria-pressed',
+      panelId: id => `map-detail-${id}`,
+      isInitiallySelected: item => item.getAttribute('aria-pressed') === 'true',
+    });
+  }
+
+  function init(doc) {
+    doc.documentElement.classList.remove('no-js');
+    doc.documentElement.classList.add('js');
+    const journey = initJourney(doc);
+    const architectureMap = initArchitectureMap(doc);
+    return { journey, architectureMap };
+  }
+
+  return {
+    createSelectionModel,
+    init,
+    initJourney,
+    initArchitectureMap,
+  };
+});

package/docs/index.html

@@ -27,6 +27,7 @@
   .cta-primary:hover { background: #79c0ff; }
   .cta-secondary { background: var(--surface); color: var(--text); border: 1px solid var(--border); }
   .cta-secondary:hover { border-color: var(--blue); color: var(--blue); }
+  .cta a:focus-visible, .feature-link:focus-visible { outline: 3px solid var(--yellow); outline-offset: 4px; }
 
   /* Container */
   .container { max-width: 1100px; margin: 0 auto; padding: 0 20px; }
@@ -43,6 +44,8 @@
   .feature { background: var(--surface); border: 1px solid var(--border); border-radius: 10px; padding: 24px; }
   .feature h3 { color: var(--blue); font-size: 1em; margin-bottom: 6px; }
   .feature p { color: var(--muted); font-size: 13px; line-height: 1.5; }
+  .feature-link { color: inherit; text-decoration: none; transition: border-color 0.2s, transform 0.2s; }
+  .feature-link:hover { border-color: var(--blue); transform: translateY(-2px); }
 
   /* Scenario sections */
   .scenario { margin: 60px 0; }
@@ -93,6 +96,7 @@
   <div class="cta">
     <a href="https://www.npmjs.com/package/@yemi33/minions" class="cta-primary">Install from npm</a>
     <a href="#quickstart" class="cta-secondary">Quick Start</a>
+    <a href="demo/memory-system.html" class="cta-secondary">Explore the Memory System</a>
   </div>
 </div>
 
@@ -114,7 +118,7 @@
   <div class="feature"><h3>Multi-Stage Pipelines</h3><p>Chain tasks, meetings, plans, and more into automated workflows. Cron triggers or manual. Artifacts flow between stages.</p></div>
   <div class="feature"><h3>Review / Fix Loop</h3><p>After implementation, Minions can dispatch reviews, react to human PR comments, and send fixes back to the original author agent.</p></div>
   <div class="feature"><h3>Git Worktree Isolation</h3><p>Each agent works in its own worktree. No conflicts, no cross-contamination, safe parallel execution.</p></div>
-  <div class="feature"><h3>Knowledge Consolidation</h3><p>Agent findings, quick notes, pinned notes, and feedback consolidate into team notes and a categorized knowledge base.</p></div>
+  <a class="feature feature-link" href="demo/memory-system.html"><h3>Interactive Memory System</h3><p>Follow findings from inbox consolidation through SQL/FTS5 retrieval, prompt bounds, provenance, fencing, and episodic capture.</p></a>
   <div class="feature"><h3>PR Integration</h3><p>Tracks Azure DevOps and GitHub PRs, including review votes, build status, merge status, human comments, and context-only links.</p></div>
   <div class="feature"><h3>Scheduled Tasks &amp; Watches</h3><p>Cron-style recurring work plus watches for PRs, work items, dispatches, meetings, pipelines, agents, and status changes.</p></div>
   <div class="feature"><h3>Command Center &amp; Doc Chat</h3><p>Natural language orchestration, persistent CC tabs, document Q&amp;A/editing, issue filing, routing updates, and local API actions.</p></div>
@@ -277,4 +281,3 @@ minions update</pre>
 
 </body>
 </html>
-

package/docs/runtime-adapters.md

@@ -263,6 +263,26 @@ Tests in `test/unit/runtime-fleet-helpers.test.js` enforce that
 `resolveAgentCli` does NOT fall through to `engine.ccCli` and that `resolveCcCli`
 does NOT inspect any agent settings.
 
+### Codex sandbox boundary
+
+Codex uses separate sandbox policies for the two runtime paths:
+
+- Command Center and doc-chat calls carry `invocationScope: 'cc'`. The Codex
+  adapter resolves `engine.codexCcSandbox`, which defaults to
+  `danger-full-access`. Interactive CC needs this access to call the localhost
+  Minions API and to write paths the operator explicitly authorizes outside
+  `~/.minions`.
+- Dispatched agents and every other Codex invocation omit the CC scope, so
+  `codex.buildArgs()` retains its `workspace-write` default. Changing
+  `engine.codexCcSandbox` cannot broaden an agent dispatch.
+
+Accepted values are `read-only`, `workspace-write`, and `danger-full-access`;
+the Settings API rejects anything else with HTTP 400. An explicit
+invocation-level `sandbox` option takes precedence over the engine setting.
+The adapter always renders the resolved policy as Codex's `--sandbox` CLI flag,
+which intentionally takes precedence over sandbox values from Codex config
+files.
+
 ## `--cli` / `--model` / `--effort` Knobs
 
 Three CLI flags switch the fleet without dashboard interaction. They are parsed

package/engine/llm.js

@@ -737,6 +737,7 @@ function callLLM(promptText, sysPromptText, opts = {}) {
     // Cross-runtime + Copilot opts:
     maxBudget, bare, fallbackModel,
     stream, disableBuiltinMcps, reasoningSummaries,
+    invocationScope,
     // P-7b2e4d01 — optional image attachments: [{ mimeType, dataBase64, filename? }]
     images,
   } = opts;
@@ -752,7 +753,7 @@ function callLLM(promptText, sysPromptText, opts = {}) {
     model, maxTurns, allowedTools, effort, sessionId,
     maxBudget, bare, fallbackModel, images: imageGate.images,
     stream, disableBuiltinMcps, reasoningSummaries,
-  }, { engineConfig: engineConfig || {} });
+  }, { engineConfig: engineConfig || {}, invocationScope });
 
   let _abort = null;
   const promise = new Promise((resolve) => {
@@ -865,6 +866,7 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
     model: modelOverride, cli: cliOverride, engineConfig,
     maxBudget, bare, fallbackModel,
     stream, disableBuiltinMcps, reasoningSummaries,
+    invocationScope,
     // P-7b2e4d01 — optional image attachments: [{ mimeType, dataBase64, filename? }]
     images,
   } = opts;
@@ -880,7 +882,7 @@ function callLLMStreaming(promptText, sysPromptText, opts = {}) {
     model, maxTurns, allowedTools, effort, sessionId,
     maxBudget, bare, fallbackModel, images: imageGate.images,
     stream, disableBuiltinMcps, reasoningSummaries,
-  }, { engineConfig: engineConfig || {} });
+  }, { engineConfig: engineConfig || {}, invocationScope });
 
   let _abort = null;
   const promise = new Promise((resolve) => {

package/engine/runtimes/codex.js

@@ -11,7 +11,13 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync, execSync } = require('child_process');
-const { FAILURE_CLASS, safeWrite, ts, resolveEngineCacheDir } = require('../shared');
+const {
+  FAILURE_CLASS,
+  safeWrite,
+  ts,
+  resolveEngineCacheDir,
+  resolveCodexCcSandbox,
+} = require('../shared');
 
 const ENGINE_DIR = __dirname.replace(/[\\/]runtimes$/, '');
 const MINIONS_DIR = path.resolve(ENGINE_DIR, '..');
@@ -388,6 +394,18 @@ function buildSpawnFlags(opts = {}) {
   return flags;
 }
 
+function resolveInvocationOptions({
+  options = {},
+  engineConfig = {},
+  invocationScope,
+} = {}) {
+  const resolved = { ...options };
+  if (invocationScope === 'cc' && resolved.sandbox == null) {
+    resolved.sandbox = resolveCodexCcSandbox(engineConfig);
+  }
+  return resolved;
+}
+
 function buildPrompt(promptText, sysPromptText, opts = {}) {
   const user = promptText == null ? '' : String(promptText);
   if (opts && opts.sessionId) return user;
@@ -967,6 +985,7 @@ module.exports = {
   spawnScript: path.join(ENGINE_DIR, 'spawn-agent.js'),
   installHint: INSTALL_HINT,
   buildSpawnFlags,
+  resolveInvocationOptions,
   buildArgs,
   buildPrompt,
   getUserAssetDirs,

package/engine/shared.js

@@ -2867,6 +2867,29 @@ function validateLiveValidation(value, opts) {
 // Single source of truth for engine configuration defaults.
 // Used by: engine.js, minions.js (init). config.template.json only has the project schema.
 
+const CODEX_SANDBOX_MODES = Object.freeze([
+  'read-only',
+  'workspace-write',
+  'danger-full-access',
+]);
+
+function validateCodexSandbox(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (typeof value !== 'string' || !CODEX_SANDBOX_MODES.includes(value)) {
+    throw _httpError(400,
+      `Invalid codexCcSandbox: "${value}". Accepted values: ${CODEX_SANDBOX_MODES.map(v => `'${v}'`).join(', ')}.`);
+  }
+  return value;
+}
+
+function resolveCodexCcSandbox(engine) {
+  const configured = engine && engine.codexCcSandbox;
+  if (configured === undefined || configured === null || configured === '') {
+    return ENGINE_DEFAULTS.codexCcSandbox;
+  }
+  return validateCodexSandbox(configured);
+}
+
 const ENGINE_DEFAULTS = {
   // W-mpxpckey000laa4f: tick interval lowered 60s → 10s so the shipped default
   // matches what operators already run at (live boxes have had `tickInterval:
@@ -3289,6 +3312,7 @@ const ENGINE_DEFAULTS = {
   defaultModel: undefined,       // fleet-wide model; undefined = let the runtime adapter pick its own default
   ccCli: undefined,              // CC/doc-chat CLI override; undefined = inherit defaultCli (independent of agent path)
   ccModel: undefined,            // CC/doc-chat model override; undefined = inherit defaultModel
+  codexCcSandbox: 'danger-full-access', // Codex CC/doc-chat only. Dispatched agents and other Codex calls keep the adapter's workspace-write default.
   claudeBareMode: false,         // Claude --bare: suppress CLAUDE.md auto-discovery (per-agent override: agents.<id>.bareMode)
   claudeFallbackModel: undefined,// Claude --fallback-model — Claude CLI honors this on rate-limit (429) only; engine retry on FAILURE_CLASS.MODEL_UNAVAILABLE keeps the flag passed so the CLI can swap internally
   copilotFallbackModel: undefined,// W-mpg6isvy000xca4d: Copilot has no --fallback-model flag; engine retry on FAILURE_CLASS.MODEL_UNAVAILABLE OVERRIDES --model directly with this value (separate knob from claudeFallbackModel because model namespaces differ across runtimes)
@@ -8806,6 +8830,9 @@ module.exports = {
   classifyInboxItem,
   isEngineSystemAlert,
   ENGINE_DEFAULTS,
+  CODEX_SANDBOX_MODES,
+  validateCodexSandbox,
+  resolveCodexCcSandbox,
   resolvePollFlag, // P-c4d8e1a3 — granular per-poller flag resolution
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentUseWorkerPool, resolveAgentAcpPoolSize, resolveAgentModel, resolveCcModel,
   resolveAgentAllowedTools, resolveAgentMaxBudget, resolveAgentBareMode, resolvePropagateClaudeMdForNonClaudeRuntimes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2420",
+  "version": "0.1.2422",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"