fix(mcp): surface prelude source discovery output

Keep print-only session eval results visible in structured MCP responses, including Clojure-style (source ...) forms that print and return nil.

Add direct depends-on hints to prelude source output so agents can discover helper contracts without guessing implementation details.

Verified with root mix precommit, mcp_server mix precommit, focused prelude tests, focused MCP lifecycle/output tests, and a ptc-bench-comparison source smoke.

Author: andreasronge

lib/ptc_runner/lisp/prelude/compiler.ex

@@ -1239,6 +1239,7 @@ defmodule PtcRunner.Lisp.Prelude.Compiler do
   defp build_source_index(specs, exports) do
     export_by_ref = Map.new(exports, &{&1.ref, &1})
     reachable = reachable_private_symbols(specs)
+    dependencies_by_ref = source_dependencies(specs, reachable)
 
     specs
     |> Enum.filter(fn %Spec{} = spec ->
@@ -1247,10 +1248,58 @@ defmodule PtcRunner.Lisp.Prelude.Compiler do
     |> Map.new(fn %Spec{} = spec ->
       ref = ref(spec.namespace, spec.symbol)
       header = source_header(ref, spec, Map.get(export_by_ref, ref))
-      {ref, header <> "\n" <> render_source_body(spec)}
+      dependencies = Map.get(dependencies_by_ref, ref, [])
+      {ref, header <> "\n" <> source_dependency_hint(dependencies) <> render_source_body(spec)}
     end)
   end
 
+  defp source_dependency_hint([]), do: ""
+
+  defp source_dependency_hint(dependencies) do
+    forms = Enum.map_join(dependencies, ", ", &"(source #{&1})")
+    ";; depends-on: #{forms}\n"
+  end
+
+  defp source_dependencies(specs, reachable_private) do
+    public_symbols =
+      specs
+      |> Enum.reject(& &1.private?)
+      |> MapSet.new(fn %Spec{} = spec -> {spec.namespace, spec.symbol} end)
+
+    indexable_symbols = MapSet.union(public_symbols, reachable_private)
+
+    specs
+    |> Enum.group_by(& &1.namespace)
+    |> Enum.flat_map(fn {ns, ns_specs} ->
+      ns_symbols = Enum.map(ns_specs, & &1.symbol)
+
+      calls =
+        Map.new(ns_specs, fn %Spec{symbol: sym, params_form: params, body_form: body} ->
+          refs =
+            body
+            |> Enum.reduce([], &collect_refs(&1, param_names(params), &2))
+            |> Enum.uniq()
+            |> Enum.filter(&(&1 in ns_symbols))
+
+          {sym, refs}
+        end)
+
+      Enum.map(ns_specs, fn %Spec{} = spec ->
+        deps =
+          calls
+          |> Map.get(spec.symbol, [])
+          |> Enum.reject(&(&1 == spec.symbol))
+          |> Enum.uniq()
+          |> Enum.filter(&MapSet.member?(indexable_symbols, {ns, &1}))
+          |> Enum.map(&ref(ns, &1))
+          |> Enum.sort()
+
+        {ref(spec.namespace, spec.symbol), deps}
+      end)
+    end)
+    |> Map.new()
+  end
+
   # `source` is a discovery convenience, so a Formatter gap must NEVER take down
   # compilation of the whole capability prelude — it degrades that one export's
   # `(source ...)` to a placeholder instead (fail-soft for cosmetics; the

mcp_server/lib/ptc_runner_mcp/envelope.ex

@@ -358,6 +358,7 @@ defmodule PtcRunnerMcp.Envelope do
   def compact_session_success(structured) do
     %{"status" => Map.get(structured, "status", "ok")}
     |> maybe_put("result", Map.get(structured, "result"))
+    |> maybe_put("prints", Map.get(structured, "prints"), keep_nil?: false)
     |> maybe_put("feedback", session_success_feedback(structured))
     |> maybe_put("validated", Map.get(structured, "validated"), keep_nil?: false)
     |> maybe_put("validated_preview", Map.get(structured, "validated_preview"), keep_nil?: false)

mcp_server/lib/ptc_runner_mcp/sessions.ex

@@ -576,7 +576,8 @@ defmodule PtcRunnerMcp.Sessions do
   end
 
   defp session_eval_payload?(payload) when is_map(payload) do
-    Map.has_key?(payload, "result") and is_map(Map.get(payload, "session"))
+    Map.get(payload, "status") == "ok" and is_map(Map.get(payload, "session")) and
+      is_map(Map.get(payload, "memory")) and Map.has_key?(payload, "history_notices")
   end
 
   defp pop_debug_structured(response) when is_map(response) do

mcp_server/test/ptc_runner_mcp/output_limits_test.exs

@@ -96,6 +96,22 @@ defmodule PtcRunnerMcp.OutputLimitsTest do
     refute text =~ "lisp_debug"
   end
 
+  test "structured session success keeps print-only nil results visible" do
+    envelope =
+      %{
+        "status" => "ok",
+        "prints" => ["(defn profile [source opts] ...)"],
+        "feedback" => "",
+        "session" => %{"session_id" => "s1", "turn" => 2}
+      }
+      |> Envelope.ptc_lisp_session_success(response_profile: :structured)
+
+    assert envelope["structuredContent"]["prints"] == ["(defn profile [source opts] ...)"]
+
+    assert get_in(envelope, ["content", Access.at(0), "text"]) =~
+             "(defn profile [source opts] ...)"
+  end
+
   test "session error text marks rollback and turn-local upstream calls" do
     text =
       Envelope.render_session_error_text(%{

mcp_server/test/ptc_runner_mcp/sessions_lifecycle_test.exs

@@ -113,6 +113,23 @@ defmodule PtcRunnerMcp.SessionsLifecycleTest do
       assert eval["structuredContent"]["result"] == "user=> 42"
     end
 
+    test "configured prelude source discovery is visible in session eval output" do
+      Config.set(Map.put(Config.get(), :prelude_source, test_prelude_source()))
+      sid = SoakHelpers.start_session()
+
+      eval =
+        call("lisp_session_eval", %{
+          "session_id" => sid,
+          "program" => "(source smoke/plus-one)"
+        })
+
+      assert eval["isError"] == false
+      assert eval["structuredContent"]["status"] == "ok"
+      assert [source] = eval["structuredContent"]["prints"]
+      assert source =~ "(defn plus-one"
+      assert get_in(eval, ["content", Access.at(0), "text"]) =~ "(defn plus-one"
+    end
+
     test "configured prelude is attached to one-shot lisp_eval" do
       Config.set(%{enabled: false, prelude_source: test_prelude_source()})
 

test/ptc_runner/lisp/prelude/discovery_test.exs

@@ -312,6 +312,15 @@ defmodule PtcRunner.Lisp.Prelude.DiscoveryTest do
       refute Map.has_key?(run_return("(ns-publics 'crm)", prelude), "normalize-id")
     end
 
+    test "public source advertises source-addressable same-namespace dependencies",
+         %{prelude: prelude} do
+      src = run_source("(source 'crm/get-user)", prelude)
+
+      assert src =~ ";; depends-on: (source crm/normalize-id)"
+      assert src =~ "(defn get-user"
+      refute src =~ "dead-helper"
+    end
+
     test "renders reader-macro literals (#(), #\"re\", 'sym) in a body without crashing compile" do
       # The source precompute renders the captured body form via Formatter. A body
       # using #() / #"re" / 'sym must not crash compilation (Formatter lacked