MindPortaliX

---

Connect your VS Code editor to the MindPortalix AI workspace. Chat with specialist agents, stream responses in real time, trigger automatic code analysis on git events, approve or deny governance human-in-the-loop pauses without leaving the editor, and follow the tamper-evident Audit Feed per agent.

See CHANGELOG.md for release history.

---

Contents

• Requirements
• Installation
• Getting an API Key
• The Configuration Panel
• The Chat Panel
• Human-in-the-Loop Approvals
• Audit Feed
• Git Trigger Behaviour
• Commands
• Build a VSIX
• Publishing to the Marketplace
• Development
• Troubleshooting
• API Key Security Notes

---

Requirements

• VS Code 1.85 or later
• A running MindPortalix server (local or remote)
• A MindPortalix API key (mpx_...) generated from your profile

---

Installation

Option A — Install from VSIX (recommended for end users)

1. Download or build mindportalix-0.1.0.vsix (see Build a VSIX below).
2. In VS Code, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
3. Run Extensions: Install from VSIX…
4. Select the .vsix file and click Install.
5. Reload VS Code when prompted.

Reinstalling a newer build over an old one? Uninstall the existing MindPortalix entry from the Extensions panel first (gear icon → Uninstall → Reload Window), then install the new VSIX — this avoids stale compiled output being served from the old extension folder.

Option B — Run in development mode (for contributors)

1. Clone the repository and open the vscode-extension/ folder in VS Code.

2. Install dependencies and compile:

   cd vscode-extension
   npm install
   npm run compile
   

3. Press F5 to launch the Extension Development Host.

4. In the new VS Code window, use the Command Palette to run any MindPortalix command.

Verifying the install

1. Ctrl+Shift+P → MindPortalix: Open Chat.
2. Check the panel header — it should read ● ready (green). If it still says ● connecting…, reload the window; the webview script may still be initializing.
3. Open the Output panel (Ctrl+Shift+U or View → Output) and select MindPortalix from the dropdown to see connection logs and errors as soon as the panel opens.

---

Getting an API Key

1. Sign in to your MindPortalix instance (default: http://localhost:3000).
2. Navigate to Profile → API Keys.
3. Click Generate New Key, enter a descriptive name (e.g. vscode-laptop).
4. Copy the key immediately — it is shown only once.
5. Paste it into the extension settings as mindportalix.apiKey.

API keys follow the format mpx_ followed by 64 lowercase hex characters. The extension will not open the chat panel until a valid key is configured.

---

The Configuration Panel

Open the Command Palette and run MindPortalix: Configure, or open VS Code Settings (Ctrl+,) and search for mindportalix. Every setting lives under the mindportalix.* namespace.

Required settings

Setting	Description	Example
mindportalix.apiUrl	URL of your MindPortalix server (no trailing slash)	http://localhost:3000
mindportalix.apiKey	Your mpx_... API key	mpx_abc123…

Optional settings

Setting	Default	Description
mindportalix.outputMode	full	full shows all agent outputs (planner, executor, reviewer, etc.) in collapsible sections; output_only shows only the final answer
mindportalix.targetBranch	main	The only branch that triggers merge analysis. Leave blank to trigger on commits to any branch
mindportalix.triggerOnCommit	true	Send an analysis query automatically after a regular commit lands on a branch other than targetBranch
mindportalix.triggerOnMerge	true	Send an analysis query when a commit lands on targetBranch
mindportalix.defaultSystemPrompt	(empty)	Text prepended to all git-triggered queries. Leave blank to use the built-in prompt
mindportalix.repoPath	(empty)	Absolute path to the local git repository root. Leave blank to auto-detect from the VS Code git extension
mindportalix.governance.enableHitl	true	Show governance human-in-the-loop approval cards in the chat panel. When disabled, pauses must be resolved from the MindPortalix web UI
mindportalix.audit.enableFeed	true	Enable the Audit tab in the chat panel (live governance audit events + browsable history)
mindportalix.audit.agentFilter	(empty)	Show audit events only for this agent id (e.g. executor). Leave blank to show all agents

Example settings.json:

{
  "mindportalix.apiUrl": "http://localhost:3000",
  "mindportalix.apiKey": "mpx_your_key_here",
  "mindportalix.outputMode": "output_only",
  "mindportalix.targetBranch": "main",
  "mindportalix.triggerOnCommit": false,
  "mindportalix.triggerOnMerge": true,
  "mindportalix.defaultSystemPrompt": "Review this change for security issues first."
}

Changes to mindportalix.apiUrl or mindportalix.apiKey take effect on the next request — no reload required.

---

The Chat Panel

Run MindPortalix: Open Chat to dock the panel beside the editor. It has two tabs: Chat and Audit (the Audit tab only appears when mindportalix.audit.enableFeed is true).

Sending a message

1. Type your message in the text area at the bottom.
2. Press Enter to send, or Shift+Enter for a new line before sending.
3. Responses stream in real time. In full output mode, each participating agent (planner, executor, reviewer, etc.) renders in its own collapsible section; in output_only mode only the final answer is shown.

Turn controls

• Deep thinking toggle — enables extended reasoning for the next query before you send it.
• Stop — interrupts an in-progress workflow mid-turn.
• Agent toolbar — collapse or expand every agent's output section at once for the current turn.
• Copy — copies the finished turn (your message + agent output) to the clipboard.
• Download — exports the finished turn as Markdown via the native Save dialog.

Streaming states

The panel header shows the connection status: ● ready (green) once the webview has initialized, ● connecting… while it's still starting up. If it stays on connecting, see Troubleshooting.

---

Human-in-the-Loop Approvals

When a MindPortalix pipeline reaches a governed stop point, it pauses server-side and the extension surfaces the decision to you. Two things trigger a pause:

• Governance Tool Bounds confirm effect — an agent action (e.g. code.execute) is configured to require explicit approval in Governance → Ecosystem Tool Bounds on the web UI.
• Front-matter human_in_the_loop agent — the architecture canvas marks an agent to run and then pause for your review of its output.

The approval card

When a confirm pause occurs, a VS Code warning notification appears (with an Open Chat button) and an approval card renders inline in the chat panel showing:

• the pause summary, the paused agent, its kind (tool-bound / agent-after) and action
• the proposed output — editable in place when the server allows it: change the text and click Approve to forward your edited version downstream
• the collapsible decision context (your original input plus prior agent results)
• Approve / Deny buttons and an Ask box

Approve resumes the pipeline (POST /api/chat/interception/:id/resolve). Deny blocks the step and the turn ends as governance-blocked. Ask sends a clarifying question to the hitl_advisor agent — grounded in the paused decision context and your workspace documents — and threads the answer under the card. Asking is a read-only side channel: it never resumes or resolves the pause; the pipeline continues only on an explicit Approve.

If the same pause is resolved elsewhere (e.g. the web UI's Interception Drawer), the card collapses automatically. If the server restarted mid-pause, resolving reports the interception as expired.

Front-matter pauses (Proceed / Abort)

A human_in_the_loop agent pauses through the chat stream itself: its question appears as an assistant message with ▶ Proceed / ✕ Abort quick-reply chips. Clicking a chip (or simply typing a reply) sends a normal chat message, which resumes the paused graph — this path never uses the interception endpoint.

Set mindportalix.governance.enableHitl: false to suppress cards and notifications; pauses then must be handled from the web UI.

---

Audit Feed

The chat panel's Audit tab shows the same tamper-evident governance ledger as the web Observatory:

• Live events stream in during chat turns (AUDIT_ENTRY over the monitor SSE connection, scoped to your user). A badge on the tab counts unseen events while you are on the Chat tab.
• History is loaded with Refresh (paginated, 50 per page, ‹ Prev / Next ›) from GET /api/monitor/audit, with agent id and action filter boxes (the agent box is prefilled from mindportalix.audit.agentFilter).
• Each row shows the decision badge (allow / deny / review), the audit level (BASIC / DETAILED / CRYPTO), agent, action, timestamp, and reason. A chain badge reports whether the SHA-256 hash chain verified for the loaded page.
• Ask on any row sends a clarifying question about that specific event to the hitl_advisor agent, grounded in the event's fields — the answer threads under the row. Like HITL asks, this is read-only.

Notes:

• Live events begin after your first chat turn in the panel (the extension learns your user id from the chat stream, then opens the user-scoped monitor connection).
• Ingress-scan audit entries carry no user tag and appear only in Refresh history, not the live stream.
• Set mindportalix.audit.enableFeed: false to disable the tab's data entirely; mindportalix.audit.agentFilter restricts both live events and history queries to one agent.

---

Git Trigger Behaviour

The extension subscribes to VS Code's built-in git extension. When a commit is made in any open repository:

• If triggerOnCommit: true and the commit is not on targetBranch → sends a commit-analysis query.
• If triggerOnMerge: true and the commit is on targetBranch → sends a merge-analysis query.

Both flags can be true simultaneously. The chat panel opens automatically and the query streams in.

---

Commands

Command	Palette	Description
MindPortalix: Open Chat	Ctrl+Shift+P → type MindPortalix	Opens the chat panel beside the editor
MindPortalix: Send Query	Ctrl+Shift+P → type MindPortalix	Shows an input box, sends the query, opens the panel
MindPortalix: Configure	Ctrl+Shift+P → type MindPortalix	Opens VS Code Settings filtered to MindPortalix
MindPortalix: Open Audit Feed	Ctrl+Shift+P → type MindPortalix	Opens the chat panel directly on the Audit tab

---

Build a VSIX

Requires vsce:

npm install -g @vscode/vsce

cd vscode-extension
npm install
npm run compile
vsce package
# produces mindportalix-0.1.0.vsix

---

Publishing to the Marketplace

scripts/release.js (invoked via npm run release) automates a full build-and-publish: it compiles the extension, packages a .vsix, and publishes it to the VS Code Marketplace in one command.

What it does

1. npm install -g @vscode/vsce — ensures the packaging/publishing CLI is available.
2. npm install — installs extension dependencies.
3. npm run compile — builds out/ from TypeScript.
4. vsce package [version] — packages mindportalix-<version>.vsix. If a version was passed, vsce bumps package.json/package-lock.json and creates a git commit + tag first.
5. Reads vscode-extension/.env for marketplace credentials.
6. vsce publish --packagePath <vsix> — publishes the exact .vsix built in step 4, using the PAT passed via environment variable (never on the command line, so it can't leak into shell history or process logs).
7. Reads the current git commit (git rev-parse --short HEAD — the version-bump commit from step 4, if one happened), stamps the Build badge at the top of this README with that hash, and renames the packaged file to mindportalix-<version>-<hash>.vsix in releases/. Commit the README change afterwards so the badge matches what's published.

What it needs

• vscode-extension/.env (gitignored, not committed) containing:

  Variable	Required	Purpose
  VSCE_PAT	Yes	Azure DevOps Personal Access Token used to authenticate the publish.
  VSCE_PUBLISHER	No	Safety check only — if set, the script aborts if it doesn't match publisher in package.json, to prevent publishing under the wrong identity.

  VSCE_PAT=your-azure-devops-pat
  VSCE_PUBLISHER=mindportalix
  

• Node/npm installed locally, and network access to npm and the Marketplace.

The script also validates any --version/-v value (must be x.y.z or a bump keyword: major, minor, patch, premajor, preminor, prepatch, prerelease) and refuses to run with anything else.

Quick start

1. Create vscode-extension/.env with your VSCE_PAT (get one from your Azure DevOps organization → Personal Access Tokens, scoped to Marketplace: Manage).

2. From the vscode-extension/ directory, run one of:

   npm run release                    # publish at the current package.json version
   npm run release -- -v patch        # bump patch version, then publish
   npm run release -- --version=1.2.0 # publish an explicit version
   

3. Watch the console output for each step (npm install -g, npm install, compile, vsce package, vsce publish). On success it prints Published <name>@<version> (build <hash>) to the Visual Studio Code Marketplace.

4. Verify the new version and Build badge on your extension's Marketplace listing page, then commit the updated README.md.

This publishes the extension live and publicly. Double-check the version and .env publisher before running.

---

Development

Project structure

vscode-extension/
├── src/
│   ├── extension.ts            # Entry point — command registration, lifecycle
│   ├── apiClient.ts            # HTTP client (no VS Code deps, independently testable)
│   ├── governanceController.ts # HITL + audit feed logic (no VS Code deps, independently testable)
│   ├── chatPanel.ts            # WebView panel — chat UI, SSE forwarding, governance wiring
│   ├── gitWatcher.ts           # VS Code git API subscription
│   └── configManager.ts        # Settings accessor
├── media/
│   ├── logo.png                 # Extension icon / marketplace logo
│   └── chat.js                  # Webview script — chat rendering, HITL card, audit tab
├── tests/
│   └── integration/
│       ├── helpers/
│       │   └── governance-app.mjs      # Shared mock server (monitor SSE, resolve, ask, audit)
│       ├── api-key.test.mjs            # API key CRUD on /api/workspace/api-keys
│       ├── chat.test.mjs               # x-api-key auth on POST /api/chat
│       ├── output-mode.test.mjs        # SSE event filtering (full vs output_only)
│       ├── hitl.test.mjs               # TC-01..09 — monitor stream, approval card, ask, resume
│       ├── audit-feed.test.mjs         # TC-10..16 — audit REST, live events, per-event ask, auth
│       └── governance-config.test.mjs  # TC-17..20 — settings gating, userId scoping
├── docs/
│   └── README.md
├── out/                        # Compiled JS (generated by tsc)
├── CHANGELOG.md
├── package.json
└── tsconfig.json

Scripts

npm run compile   # compile TypeScript → out/
npm run watch     # watch mode (recompiles on save)
npm test          # run all integration tests

Running integration tests

The tests run against in-memory mocks — no live server, Supabase, or LLM calls needed. The governance tests import from the compiled out/ directory, so compile before testing:

cd vscode-extension
npm run compile && npm test

The governance/audit suites (hitl, audit-feed, governance-config) cover 20 cases (TC-01..TC-20): monitor SSE parsing, approve/deny/edited-approve/expired resolution, advisor asks (never resuming), front-matter resume-via-message, audit pagination/filters/live dispatch, per-event asks, x-api-key auth on the new endpoints, settings gating, and user-scoped connection lifecycle.

---

Troubleshooting

"API key not configured" warning when opening chat Run MindPortalix: Configure and ensure mindportalix.apiKey is set and starts with mpx_.

Send button does nothing (no message appears) The webview script may be blocked. Reload the Extension Development Host window (Ctrl+Shift+P → Developer: Reload Window). If you installed from a .vsix, rebuild it from the latest source and reinstall.

"Error: Chat request failed: HTTP 401" Your API key is missing, revoked, or malformed. Generate a new one from Profile → API Keys on your MindPortalix instance.

"Error: connect ECONNREFUSED" The MindPortalix server is not reachable. Confirm it is running and that mindportalix.apiUrl points to the correct address and port.

Chat panel shows no response (blank assistant bubble) Check the MindPortalix server logs for errors. If the send button stays disabled after clicking, close and reopen the chat panel — this resets the streaming state.

Git triggers not firing Ensure the built-in vscode.git extension is enabled. Check that triggerOnCommit or triggerOnMerge is true and the API key is valid.

Approval card never appears for a paused pipeline Check that mindportalix.governance.enableHitl is true and that you have sent at least one chat message in the panel this session — the live monitor connection opens only after the extension learns your user id from the first chat turn. Verify the pause exists in the web UI (Interception Drawer).

Approve says the interception expired The pause was already resolved (possibly from the web UI) or the server restarted, dropping the in-memory suspension. Re-run the query to trigger a fresh pause.

Audit tab stays empty Ensure mindportalix.audit.enableFeed is true. Live events only appear after your first chat turn; click Refresh to load history instead. If Refresh errors, note the audit endpoint is rate-limited to 100 requests/minute, and ingress-scan entries appear only in history (they carry no user tag for the live stream). Also check mindportalix.audit.agentFilter — a filter for one agent hides all others.

---

API Key Security Notes

• API keys are stored as SHA-256 hashes server-side; the plaintext is never persisted after creation.
• The x-api-key header is used for all authenticated requests from the extension.
• Each key is scoped to a single user account.
• Revoke a key from Profile → API Keys; it is rejected immediately on the next request.