llm.txt

# Soar VS Code Extension – Agent Index

This file is a high-level index of the whole extension so an agent can quickly
locate the right implementation area.

## What this extension does

Soar language support in VS Code with:

- syntax highlighting
- language server integration
- datamap editing and validation
- VisualSoar project structure editing
- project creation/sync/validation
- MCP server for LLM/agent workflows
- socket-based debug adapter integration for remote Soar kernel control (SML XML)

## Core architecture (where to start)

- Extension entrypoint: `src/extension.ts`
  - command registration
  - tree view wiring (Datamap + Project Structure)
  - validation triggers (auto-validate on save/open, skip files matched by `.soarignore`)
  - `.soarignore` cache invalidation via `FileSystemWatcher` + `soarIgnoreCache` module variable
  - MCP auto-registration hook
- Types and project schema model: `src/server/visualSoarProject.ts`
- Project load/save + schema validation: `src/server/projectLoader.ts`
- Shared ID generation helper: `src/server/idGeneration.ts`
  - canonical `generateVertexId` used across datamap/layout/MCP flows

## Feature map: where to look for specific code

### Project management and active project state

- `src/projectManager.ts`
  - project discovery (`.vsa.json` scanning)
  - active project selection/restore/clear
  - active-project persistence for MCP: `.vscode/soar-active-project.json`
  - project validation diagnostics (missing/orphaned files)
  - orphaned-file diagnostics respect `.soarignore` (via `ProjectSync`)

### Datamap tree + CRUD

- `src/datamap/datamapTreeProvider.ts`
  - datamap tree rendering and root switching
  - search filter: `setSearchFilter(text)` / `searchFilter` — filters children by attribute name; toggled via `soar.searchDatamap` / `soar.clearDatamapSearch` commands; VS Code context key `soar.datamapSearchActive` drives toolbar icon swap
  - sort mode: `setSortEnabled(bool)` / `sortEnabled` — sorts children by type priority (SOAR_ID → ENUMERATION → INTEGER → FLOAT → STRING → JAVA_FILE) then alphabetically; toggled via `soar.toggleDatamapSort` / `soar.disableDatamapSort`; VS Code context key `soar.datamapSortEnabled`
- `src/datamap/datamapOperations.ts`
  - add/edit/delete attributes
  - edit flow supports updating enumeration values (e.g., `^impasse` choices)
  - edit flow supports parent reassignment:
    - `Change Parent`: move attribute (and referenced subtree) to a new SOAR_ID parent
    - `Change Parent + Link`: move ownership and keep a linked reference on previous parent
  - linked attribute operations
  - uses shared `generateVertexId` for new datamap vertices
  - datamap persistence and metadata refresh
- `src/datamap/datamapMetadata.ts`
  - ownership/link metadata, inbound edge maps, path/attribute helpers

### Datamap validation

- `src/datamap/datamapValidator.ts`
  - validates Soar attributes against datamap
  - variable binding/path checks
  - enum value validation
  - infers `<s>` state context from explicit `^name` tests and, when needed,
    from layout file location (high-level operator substate ancestry)
  - VS Code diagnostics creation (with non-VSCode-safe fallback used by MCP)

### Datamap structural integrity

- `src/datamap/datamapMetadata.ts`
  - ownership/link metadata, inbound edge maps, path/attribute helpers
  - `DatamapMetadataCache.checkLinkedAttributeIntegrity(project, datamapIndex)`
    — static method; returns `DatamapIntegrityIssue[]` with two kinds:
    - `dangling`: edge whose `toId` is not present in the datamap index at all
    - `unreachable-root`: linked attribute (shared-target edge) whose target
      vertex cannot be reached from the datamap root via the ownership DFS
  - `DatamapIntegrityIssue` carries `kind`, `parentVertexId`, `attributeName`,
    `targetVertexId`, and a human-readable `message`
  - called automatically by `validateProjectAgainstDatamap` (result appears in
    `ValidationSummary.datamapIssues`) and exposed standalone via the MCP tool
    `datamap_check_integrity`
- Deletion clean-up (`src/datamap/datamapOperations.ts`):
  - `DatamapOperations.removeVertexRecursive` (public static): two-pass
    strategy — collect full subtree IDs, then sweep every SOAR_ID vertex and
    strip any outgoing edge pointing into the deleted set, preventing dangling
    link edges after an owned-vertex deletion
  - `DatamapOperations.deleteAttributeCore(context, parentVertexId, attributeName, removeLinkOnly?)`
    (public static): pure deletion logic with no VS Code UI calls. Removes the
    named edge from the parent, determines ownership via `ownerParentId` from
    edge metadata, calls `removeVertexRecursive` when appropriate, saves the
    project, and returns `{ parentVertexId, attributeName, targetVertexId, removedAsLinkOnly }`.
    Used directly by tests and delegated to by both the UI path and MCP layer.
  - `DatamapOperations.deleteAttribute` (public static): UI path — shows a
    confirmation dialog (`showWarningMessage`) then delegates to
    `deleteAttributeCore`
  - `SoarMcpCore.deleteAttribute`: thin wrapper — loads context, delegates to
    `DatamapOperations.deleteAttributeCore`

### Layout / project structure editing

- `src/layout/layoutTreeProvider.ts`
- `src/layout/layoutOperations.ts`
  - uses shared `generateVertexId` when creating datamap vertices for layout-driven edits
- `src/layout/projectSync.ts`
  - shared project-file gathering helpers (including existing `.soar`
    collection) reused by project-wide datamap validation flows
  - `findOrphanedFiles()` loads `.soarignore` via `soarIgnore.ts` and skips
    matching files before returning
- `src/layout/soarIgnore.ts`
  - `loadSoarIgnore(projectRoot)` – reads `.soarignore` (next to `.vsa.json`)
    using gitignore semantics (`ignore` npm package); returns an `Ignore`
    instance (empty = nothing ignored if file absent)
  - `isIgnoredByPatterns(ig, relativePath)` – returns true if the path should
    be excluded
  - `DEFAULT_SOARIGNORE_CONTENT` – template written to new projects
- `src/layout/projectCreator.ts`
  - creates a default `.soarignore` file in the project root on project creation
- `src/layout/undoManager.ts`

### Soar parsing and language server

- `src/server/soarParser.ts`
- `src/server/soarLanguageServer.ts`
- `src/client/lspClient.ts`

### Debug adapter (SML socket transport)

- `src/debug/smlSocketClient.ts`
  - strongly typed SML XML socket client
  - 4-byte big-endian length framing
  - call/response correlation via `ack`
  - auto-reply for inbound `doctype=call` messages
  - persistent socket behavior (no user-configurable idle timeout)
- `src/debug/soarSmlDebugAdapter.ts`
  - inline DAP adapter implementation (`vscode.DebugAdapter`)
  - DAP→SML mapping for initialize/launch/threads/stackTrace/scopes/variables/
    continue/next/stepIn/stepOut/pause/evaluate/disconnect
  - DAP thread model maps one thread per Soar agent discovered from `get_agent_list`
  - DAP call stack maps to goal-stack states per selected thread/agent and is recomputed on stop/stack requests; frames are returned current→root so VS Code auto-selects current state
  - stable identity maps preserve deterministic IDs across session lifetime: agent→threadId, state→frameId, objectKey→variablesReference
  - advertises DAP `supportsInvalidatedEvent` and emits `invalidated` (`all`) after each stop to force Watch/Variables/UI refresh
  - `scopes` returns `Working Memory`, `Operator`, and `IO Link` sections for each selected state frame
  - Variables section targets: `Working Memory` uses `print <state> -d <printDepth> -t`, `Operator` uses `print <o> -d <printDepth> -t`, and `IO Link` uses `print I1 -d <printDepth> -t`
  - Variables depth is user-configurable via debug configuration `printDepth`
  - `variables` resolves structured WMEs (identifier-expansion via stable references) from section/identifier contexts
  - always emits an initial `stopped` event on connect to select first stack frame automatically
  - stop transitions (`entry`/`step`/`pause`) emit `preserveFocusHint: false` so VS Code focuses the newest selected frame
  - no editable Variables entries; command interaction is handled via Watch/Debug Console evaluate requests
  - applies configurable `printDepth` (`-d`) and `printTree` (`-t`) formatting to Variables and Watch print rendering
  - watch evaluation is frame-context aware (`frameId`→state) and returns stable identifier references when possible
  - watch evaluation is fault-tolerant: retries once on transient post-step failures and returns `<unavailable: ...>` value (success response) instead of DAP error
  - execution mapping uses `cmdline run` for continue and `cmdline stop` on pause when session is running
  - `evaluate` forwards Debug Console (`repl` context) input directly as Soar CLI command text and resolves non-REPL expressions in frame context
  - supports custom request `soarSetVariablesDepth` to update Variables depth at runtime and emit `invalidated` for variables
  - debug configuration provider + descriptor factory for debug type `soar-sml`
- `src/debug/stopPhaseTreeProvider.ts`
  - sidebar tree data provider for stop-phase selection with phases `input`, `proposal`, `decision`, `apply`, `output`
  - defaults selection to `apply` (Soar default stop-before phase)
  - parses status output from `soar stop-phase` (`Stop before <phase>`) for UI synchronization
  - tracks selected phase in-view and executes `soar.setStopPhase` command from tree items

### MCP / LLM integration

- `src/mcp/soarMcpTools.ts`
  - MCP tool definitions and schemas
- `src/mcp/soarMcpServer.ts`
  - MCP stdio server and request handlers
  - project-scoped tool calls are serialized per `projectFile` to prevent
    concurrent load/modify/save races
- `src/mcp/soarMcpCore.ts`
  - reusable core operations invoked by MCP tools
  - `datamap_update_attribute_edge` supports enum value updates via optional
    `enumChoices` for enumeration targets (including impasse value sets)
  - generates VisualSoar-style hex string IDs for new datamap vertices and
    layout nodes
  - owns persistent SML runtime bridge state for MCP (`agent_runtime_connect` lifecycle,
    current agent tracking, `soarCycleExecuting`/paused state)
  - `agent_runtime_connect` probes kernel `version` and `get_agent_list` immediately
    after socket connect; initial agent-list probe now depends on connected
    client state (not pre-existing session state)
  - executes Soar runtime commands over socket via `SmlSocketClient`
- `src/mcp/toolExecutionQueue.ts`
  - keyed async execution queue used by MCP server for safe parallelism
- `src/mcp/mcpRegistration.ts`
  - workspace MCP registration (`.vscode/mcp.json`)
  - writes MCP server command as `node <extension>/dist/mcpServer.js`

For MCP details (tool names, payloads, logging, and active-project behavior),
start in these four files.

Current MCP coverage includes datamap CRUD, datamap structural integrity checks,
project-vs-datamap validation, active-project lookup, layout additions
(operator/impasse operator/file/folder), and remote runtime control for running
kernels via SML socket:

- `agent_runtime_connect` / `agent_runtime_disconnect`
- `agent_runtime_get_status` — returns `{ running: bool, soarCycleExecuting: bool, host, port, currentAgent }`;
  `running` is true when the connection is alive; `soarCycleExecuting` is true only while decision cycles are executing
- `agent_runtime_list_agents`
- `agent_runtime_run_decision_cycles` / `agent_runtime_step_decision_cycles` / `agent_runtime_pause`
  — these return `soarCycleExecuting` (not `isRunning`) in their result
- `agent_runtime_exec_cli` — generic CLI escape hatch for advanced/large-context LLMs
- Individual Soar CLI command tools (for smaller/local LLMs that need explicit schemas):
  - `agent_runtime_cli_production` — `production <subcommand>` (break/excise/find/firing-counts/matches/memory-usage/optimize-attribute/watch)
  - `agent_runtime_cli_print` — `print [options] [target]` (working memory, production memory, stack, GDS)
  - `agent_runtime_cli_preferences` — `preferences [options] [identifier [attribute]]`
  - `agent_runtime_cli_epmem` — `epmem [subcommand]` (enable/disable/get/set/stats/timers/viz/print/backup)
  - `agent_runtime_cli_explain_track_operator` — `explain track-operator [<name>|--all]` (track one operator, track all, or list tracked operators)
  - `agent_runtime_cli_explain_untrack_operator` — `explain untrack-operator <name|all>` (exclude one operator from tracking, or disable all-mode)
  - `agent_runtime_cli_explain_operator` — `explain operator <name> [--json]` (decision-cycle explanation data for tracked operators)

## User commands and settings (key extension contract)

See `package.json` (contributes/commands/configuration) and `src/extension.ts`
(runtime command wiring).

- Legacy smoke-test command `soar.helloWorld` has been removed from both
  `package.json` contributions and `src/extension.ts` registrations.
- New command `soar.validateSelectedProjectAgainstLsp` runs LSP-based checks
  across all existing project `.soar` files (project-wide Problems panel refresh).
- New command `soar.checkDatamapIntegrity` runs `DatamapMetadataCache.checkLinkedAttributeIntegrity`
  on the active project and shows a summary notification; a "Show Details" action
  opens a plaintext report listing every issue by kind, attribute name, and vertex IDs.
  The command is also exposed as an icon button in the Datamap view title bar.

Debug contract additions:

- `package.json` contributes debugger type `soar-sml` with launch attributes:
  `host`, `port`, `agent`, `printDepth`, `printTree`, `stopOnEntry` (`stopOnEntry` retained for compatibility; adapter auto-stops on connect)
- `src/extension.ts` registers debug configuration provider and debug adapter
  descriptor factory for `soar-sml`
- `package.json` contributes `soarStopPhase` sidebar view and commands
  `soar.setStopPhase` / `soar.refreshStopPhaseView` / `soar.setVariableViewDepth`
- `soarStopPhase` is contributed to VS Code's built-in Debug view container (not the custom Soar activity container)
- `src/extension.ts` wires stop-phase selection to active `soar-sml` sessions via
  DAP `evaluate` with `context: repl`, issuing `soar stop-phase <phase>`
  and queries `soar stop-phase` on debug-start/refresh to reflect current kernel state
- `src/extension.ts` exposes runtime Variables depth control (`soar.setVariableViewDepth`) via
  custom request `soarSetVariablesDepth` on the active `soar-sml` session

## Data and persistence locations

- Project file format: `.vsa.json` (VisualSoar-compatible)
- Datamap and layout persist into project file directly
- Workspace MCP config: `.vscode/mcp.json`
- Active project state for MCP: `.vscode/soar-active-project.json`

## Build, test, and quality checks

- Build: `npm run compile`
- Watch: `npm run watch`
- Lint: `npm run lint`
- Unit tests: `npm test`
- VS Code integration tests: `npm run test:ci`
- Markdown lint ignores `CHANGELOG.md` via `.markdownlintignore`
- GitHub tag release workflow (`.github/workflows/ci.yml`, `release` job):
  packages VSIX, generates latest release notes via git-cliff (`cliff.toml`, `--latest`) into `release-notes.md`, and publishes with `softprops/action-gh-release` using `body_path`
  - changelog entries include a short linked commit SHA to the repository commit URL

## Test index (where behavior is validated)

- Test bootstrap: `test/helpers/index.ts`
- Manual debug launch setups: `test/.vscode/launch.json`
  - includes Extension Host launch and `soar-sml` socket debug configuration for local end-to-end adapter checks
- MCP tests: `test/mcp/helpers/*`
  - includes queue safety coverage in `tool-execution-queue.test.ts`
  - includes ID format regression checks in `id-generation.test.ts`
  - includes datamap attribute enum update coverage in `update-attribute.test.ts`
- Datamap validation fixtures: `test/lsp/datamap/*`
  - includes structural integrity checks and deletion clean-up tests in
    `test/lsp/datamap/helpers/datamap-integrity.test.ts`
    (uses `DatamapMetadataCache`, `DatamapOperations.deleteAttributeCore`,
    and `ProjectLoader` directly — no MCP dependency)
- Layout/undo tests: `test/layout/*`
- Datamap manipulation scenarios: `test/datamap-manipulation/*`
  - includes parent reassignment coverage in
    `test/datamap-manipulation/fixtures/parent-reassignment.test.ts`
- Legacy project compatibility: `test/legacy-agents/*`

## Agent usage guidance

When asked to modify behavior, first map the request to one of the sections
above and open those files before changing code. Prefer reusing existing core
logic (especially in datamap and project loader flows) rather than creating
parallel implementations.