betterthantomorrow Backseat Driver Extension Internals
Subsystem contracts, state architecture, and temporal sequences for the Backseat Driver extension.
Key Namespaces
| Namespace | Purpose |
|---|---|
ex.ex |
Dispatcher — the only entry point for state changes |
ex.ax |
Action routing, enrichment, accumulation |
ex.fx |
Effect routing (context-enriched before domain dispatch) |
app.db |
!app-db atom, !output-conn & !history-conn Datascript, serialization |
app.axs |
App lifecycle actions (activate, init, commands, cleanup) |
app.fxs |
App effects (logging, command registration, Language Model tools) |
db.axs |
Generic state mutation actions (assoc-in, update-in) |
mcp.axs |
MCP server lifecycle actions (start/stop/error/handle-request) |
mcp.fxs |
MCP effects (start/stop server, notifications, request handling, wrapper copy) |
mcp.server |
TCP socket server implementation (low-level net, port file, buffering) |
mcp.requests |
MCP protocol handler — tool listings, initialize, tools/call dispatch |
mcp.skills |
Skill frontmatter parsing, filtering, instruction composition |
mcp.logging |
MCP server log output |
extension |
VS Code activate/deactivate entry points |
integrations.calva.api |
Calva API access (REPL eval, ranges, editor, document, info) |
integrations.calva.editor |
Structural editing implementation |
integrations.calva.editor-util |
File context formatting (line-numbered windows) |
integrations.vscode.tools |
VS Code Language Model tool registration |
integrations.parinfer |
Bracket balancing via Parinfer |
stdio.wrapper |
MCP stdio-to-socket relay (dist/calva-mcp-server.js) |
Subsystem Contracts
λ app_db_contract.
db/!app-db ≡ atom {
:vscode/extension-context ExtensionContext ;; set before dispatch, circular refs
:app/getConfiguration fn ;; VS Code config reader
;; From init-db
:extension/disposables [Disposable] ;; VS Code subscriptions
:extension/when-contexts {:calva-mcp-extension/activated? bool
:calva-backseat-driver/started? bool
:calva-backseat-driver/starting? bool
:calva-backseat-driver/stopping? bool}
:calva/output-line-counter int ;; monotonic for output entities
;; From initial-state (extension.cljs)
:app/log-file-uri Uri ;; log location
:app/min-log-level keyword ;; :debug/:info/:warn/:error
:mcp/wrapper-config-path string ;; ~/.config/calva/backseat-driver
:calva/history-storage-uri Uri|nil ;; eval-history.transit.json
;; Runtime
:app/log-dir-initialized+ promise ;; resolved when log dir exists
:app/server-info {:server/instance Server
:server/port int
:server/port-file-uri Uri
:server/port-note string?}
}
| inspection: always(dissoc :vscode/extension-context) | circular_ref_guard
| mutation: only_through_dispatch! | ¬direct_swap!
λ ex_dispatcher_contract.
dispatch!(context, actions) ≡ the_only_state_entry_point
| ~16 lines of code | the entire framework
|
| flow:
| ax/handle-actions(@!app-db, context, actions)
| reduce_over_actions:
| 1. enrich-from-context(action, context) → :context/x.y → js-get-in
| 2. enrich-from-state(action, state) → [:db/get k], :vscode/config.x
| 3. route_by(namespace action-kw) → domain_handler
| 4. handler_returns {:ex/db, :ex/fxs, :ex/dxs}
| accumulate: merge_db, into_fxs(enriched_from_state), into_dxs
| when db → reset!(!app-db)
| when dxs → recursive dispatch!(context, dxs)
| when fxs → for_each: enrich_from_context → route → execute
λ enrichment_contract.
context_enrichment:
:context/x.y.z → js-get-in(context, ["x" "y" "z"])
| applied_to: actions ∧ effects
state_enrichment:
[:db/get key] → (get state key)
:vscode/config.settingName → VS Code configuration API
| applied_to: actions_only (effects get context enrichment only)
args_enrichment:
:ex/action-args → entire_result_from_effect
:ex/action-args%N → (nth result (dec N))
| applied_to: continuation_actions_via :ex/then
λ action_routing.
(namespace action-kw) → handler_namespace:
"app" → app.axs
"mcp" → mcp.axs
"db" → db.axs
"vscode" → integrations.vscode (via axs)
"node" → integrations.node (via axs)
"calva" → integrations.calva (via axs)
| new_domain → add_case_in ex/ax.cljs handle-action
λ effect_routing.
(namespace fx-kw) → handler_namespace:
"app" → app.fxs
"mcp" → mcp.fxs
"vscode" → integrations.vscode (via fxs)
"node" → integrations.node (via fxs)
"calva" → integrations.calva (via fxs)
| effects_receive(dispatch!, context, enriched-fx)
| new_domain → add_case_in ex/fx.cljs perform-effect!
λ datascript_contract.
!output-conn ≡ session_scoped | schemaless | cap: 1000 entities
| all_output_categories: evaluationResults, evaluatedCode, evaluationOutput,
| evaluationErrorOutput, otherOutput, otherErrorOutput
!history-conn ≡ persistent | schema: {:output/line {:db/unique :db.unique/identity}}
| cap: 10000 | evaluatedCode_only
| serialized_to: eval-history.transit.json | cognitect.transit JSON
| format: {:format-version 1 :entities [...]}
entity_attributes:
:output/line int (monotonic, from :calva/output-line-counter)
:output/category string
:output/text string
:output/who string?
:output/timestamp inst
:output/ns string?
:output/repl-session-key string?
λ mcp_server_contract.
socket_server: TCP | net.createServer | localhost_only
| port: configured(default 1664) | 0 ≡ random | EADDRINUSE → fallback_to_0
| port_file: ${workspaceFolder}/.calva/mcp-server/port
| protocol: newline_delimited_JSON | buffered_partial_reads
| active_sockets: atom | tracks_connected_clients
| notifications: broadcast_to_all_active_sockets
stdio_wrapper: dist/calva-mcp-server.js
| reads_port_from_port_file → TCP_connect → relay(stdio ↔ socket)
| one_server_per_workspace_folder
λ calva_api_contract.
calva-api ≡ {
:repl {:evaluateCode, :currentSessionKey, :onOutputLogged}
:ranges {:currentTopLevelForm, :currentEnclosingForm, ...}
:editor {:replace}
:document {:getNamespace, :getNamespaceAndNsForm}
:info {:getSymbolInfo, :getClojureDocsDotOrg}
}
| accessed_at: integrations.calva.api/calva-api
| capability_gated: tools_appear_disappear_based_on_calva_support
λ structural_editing_contract.
editing_unit ≡ top_level_form | ¬lines_of_text
| parinfer: bracket_balancing | integrations/parinfer.cljs
| targeting: targetLineText + line ±2 scan_window
| rich_comments: forms_inside(comment ...) ≡ top_level
| diagnostic_context: 21_line_window | line_numbers | → arrow_marker
| bottom_to_top: multiple_edits_highest_line_first
Temporal Sequences
λ activation_sequence.
1_vscode_calls: extension.activate(context) | entry_point
2_store_context: assoc(:vscode/extension-context) into !app-db | before_dispatch
3_store_config_reader: assoc(:app/getConfiguration) | vscode/workspace.getConfiguration
4_dispatch_activate: [:app/ax.activate (initial-state context)]
5_ax.activate: merge(init-db, initial-state) | set when-contexts | dispatch ax.init
6_ax.init: register_commands ∧ language_model_tools | init_output_listener
7_fx.init-logging: ensure_log_directory | resolve(:app/log-dir-initialized+)
8_fx.copy-wrapper-script: copy(calva-mcp-server.js) to(~/.config/calva/backseat-driver/)
9_auto_start_check: if(:vscode/config.autoStartMCPServer) → dispatch(ax.start-server)
| skip(2) → enrichment_fails | context_not_available
| skip(8) → stdio_wrapper_missing | MCP_clients_cant_connect
λ mcp_server_lifecycle.
start:
1_dispatch: [:mcp/ax.start-server]
2_set_starting: when-context(starting? → true, stopping? → false)
3_fx.start-server → server/start-server!+
3a_create_server: net.createServer(TCP)
3b_listen: configured_port | EADDRINUSE → port_0
3c_write_port_file: .calva/mcp-server/port
4_ax.server-started: store(:app/server-info) | when-context(started? → true, starting? → false)
5_fx.show-server-started-message: info_notification_with_port
client_connection:
1_socket_connects: stdio_wrapper → TCP_connect(port)
2_data_handler: UTF-8 | buffer → split(\n) → parse_JSON
3_dispatch: [:mcp/ax.handle-request parsed-message]
4_fx.handle-request → requests/handle-request-fn
5_response: write_JSON\n_to_socket
stop:
1_dispatch: [:mcp/ax.stop-server]
2_set_stopping: when-context(stopping? → true)
3_fx.stop-server → server/stop-server!+
3a_end_sockets: end+destroy_all_active_sockets
3b_close_server: server.close()
3c_delete_port_file: vscode_workspace.fs | node_fs_fallback
4_ax.server-stopped: clear(:app/server-info) | when-context(started? → false, stopping? → false)
λ mcp_request_flow.
initialize → {:protocolVersion "2024-11-05", :capabilities, :instructions (compose-instructions)}
tools/list → read(package.json languageModelTools) → transform_to_mcp_format | capability_filtered
tools/call → multimethod(handle-tool-call) by(:name) → {:content [{:type :text :text result}]}
resources/list → skill_manifests | filtered_by_settings
resources/read → read(assets/skills/{name}/SKILL.md) | full_content
λ tool_registration_sequence.
1_package_json: languageModelTools manifest (name, description, inputSchema, when-clause)
2_activation: ax.register-language-model-tools → fx.register-language-model-tools
3_vscode_api: tools.cljs registers with Language Model API
4_mcp_server: requests.cljs reads same manifests at runtime
5_capability_gating: tools conditionally available based on Calva version + settings
| single_source_of_truth: package.json | change_once → applied_everywhere
λ hot_reload_sequence.
1_edit_source: modify .cljs file | save
2_shadow_detects: file_watcher → incremental_compile
3_compile: cljs → js | check_for_warnings
4_extension_host: picks_up_changes | ¬restart_needed
5_verify: re_evaluate_in_repl | require_with_reload
| zero_warnings_policy: new_warnings_stand_out_only_when_baseline_clean
| package_json_changes → extension_host_restart_required
Interactive Development Patterns
;; Explore runtime state
(in-ns 'calva-backseat-driver.app.db)
(dissoc @!app-db :vscode/extension-context)
;; Test Calva API
(in-ns 'calva-backseat-driver.integrations.calva.api)
(keys (:repl calva-api))
;; Inspect MCP server state
(in-ns 'calva-backseat-driver.mcp.server)
@active-sockets
;; Query output log
(in-ns 'calva-backseat-driver.app.db)
(d/q '[:find ?text :where [?e :output/category "evaluatedCode"] [?e :output/text ?text]] @!output-conn)
;; Test enrichment
(in-ns 'calva-backseat-driver.ex.ax)
(enrich-from-context [:some/ax.test :context/subscriptions] context)
Configuration Settings
| Setting | Type | Default | Purpose |
|---|---|---|---|
enableMcpReplEvaluation |
boolean | true | Expose REPL eval via MCP (set false to disable) |
mcpSocketServerPort |
number | 1664 | Socket server port (0 = random) |
autoStartMCPServer |
boolean | false | Start MCP server on activation |
provideBdSkill |
boolean | true | Provide Backseat Driver skill via MCP |
provideEditSkill |
boolean | true | Provide structural editing skill via MCP |
Settings accessed via enrichment: :vscode/config.settingName in action handlers.