backseat-driver-internals

name: backseat-driver-internals description: 'Backseat Driver extension internals — Ex framework contracts, app-db state architecture, MCP socket server lifecycle, enrichment system, Datascript output log, activation sequences, and namespace reference. Use when: modifying core extension code, debugging state issues, working with app-db or Ex framework, understanding activation or MCP server flow, investigating enrichment or Datascript connections, or working with tool registration.'

Backseat Driver Extension Internals

Subsystem contracts, state architecture, and temporal sequences for the Backseat Driver extension.

Key Namespaces

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

Settings accessed via enrichment: :vscode/config.settingName in action handlers.