refactor(agent): extract agent+shared into standalone packages with full GRACE semantic markup

- Move agent code from backend/src/agent/ to agent/src/ss_tools/agent/
- Extract shared stdlib-only utilities to shared/src/ss_tools/shared/
- Add #region/#endregion contracts to all ~140 functions (INV_1 compliance)
- Update docker files, entrypoint, build scripts for new package layout
- Backend now imports ss_tools.shared._llm_health (no gradio/langchain deps)
- Add specs for 036-039 feature plans

agent/tests/test_agent_summarise.py

@@ -0,0 +1,73 @@
+# #region Test.AgentChat.ToolSummarise [C:3] [TYPE Module] [SEMANTICS test,agent,tools,summarise]
+# @BRIEF Contract tests for _summarise_response — structured truncation.
+# @RELATION BINDS_TO -> [AgentChat.Tools.Summarise]
+# @TEST_EDGE: json_array_50_items -> Large JSON arrays summarised as top-5 + count.
+# @TEST_EDGE: short_text_passthrough -> Text ≤ limit returned unchanged.
+# @TEST_EDGE: json_object_keys_sample -> Large JSON objects summarised as keys + sample.
+# @TEST_EDGE: non_json_sentence_boundary -> Non-JSON text truncated at sentence boundary.
+
+import json
+
+from ss_tools.agent.tools import _summarise_response
+
+
+# #region test_summarise_json_array_50_items [C:2] [TYPE Function]
+# @BRIEF JSON array with 50 items → top-5 summary with remaining count.
+def test_summarise_json_array_50_items():
+    """Large JSON arrays summarise with top-5 items and remaining count."""
+    items = [{"id": i, "name": f"item-{i}"} for i in range(50)]
+    text = json.dumps(items)
+
+    summary = _summarise_response(text, limit=200)
+
+    assert summary.startswith("Found 50 items:")
+    assert "item-0" in summary
+    assert "item-4" in summary
+    assert "... and 45 more items." in summary
+# #endregion test_summarise_json_array_50_items
+
+
+# #region test_summarise_short_text_passthrough [C:2] [TYPE Function]
+# @BRIEF Text ≤ limit is returned unchanged (no truncation, no JSON parse overhead visible).
+def test_summarise_short_text_passthrough():
+    """Text within limit is returned unchanged."""
+    text = "This is a short response."
+
+    result = _summarise_response(text, limit=100)
+
+    assert result == text
+# #endregion test_summarise_short_text_passthrough
+
+
+# #region test_summarise_json_object_keys_sample [C:2] [TYPE Function]
+# @BRIEF Large JSON object → key list + sample values.
+def test_summarise_json_object_keys_sample():
+    """Large JSON objects are summarised with keys and sample values."""
+    data = {f"key_{i}": f"value_{i}" * 50 for i in range(20)}
+    text = json.dumps(data)
+
+    summary = _summarise_response(text, limit=100)
+
+    assert summary.startswith("Result keys: ")
+    assert "Sample: " in summary
+# #endregion test_summarise_json_object_keys_sample
+
+
+# #region test_summarise_non_json_sentence_boundary [C:2] [TYPE Function]
+# @BRIEF Non-JSON long text truncated at last sentence boundary before limit.
+def test_summarise_non_json_sentence_boundary():
+    """Non-JSON text truncates at last sentence boundary with trailing ellipsis."""
+    text = ("This is sentence one. " * 100)
+
+    summary = _summarise_response(text, limit=500)
+
+    # Must end with ellipsis
+    assert summary.endswith("...")
+    # Must be shorter than or equal to limit + 3 (ellipsis)
+    assert len(summary) <= 500
+    # Must retain at least one sentence boundary before the ellipsis
+    assert ". " in summary[:-3]
+# #endregion test_summarise_non_json_sentence_boundary
+
+
+# #endregion Test.AgentChat.ToolSummarise