feat(planner): persist reusable action semantics

skills_learning/synthesis.py

@@ -40,7 +40,14 @@ def extract_tool_calls(
         tool_name = str(tool_call.get("action") or tool_call.get("tool_name") or "")
         if not tool_name or tool_name in READ_ONLY_TOOL_NAMES:
             continue
-        steps.append(FlowStep(tool_name=tool_name, args=dict(tool_call.get("args") or {})))
+        steps.append(
+            FlowStep(
+                tool_name=tool_name,
+                args=dict(tool_call.get("args") or {}),
+                purpose=_optional_text(tool_call.get("purpose")),
+                expected_outcome=_optional_text(tool_call.get("expected_outcome")),
+            )
+        )
     return steps
 
 
@@ -105,11 +112,15 @@ def promote_parameters(
     existing_parameters: dict[str, dict[str, Any]] | None = None,
 ) -> tuple[list[FlowStep], dict[str, dict[str, Any]]]:
     parameters = {
-        name: dict(schema)
-        for name, schema in (existing_parameters or {}).items()
+        name: dict(schema) for name, schema in (existing_parameters or {}).items()
     }
     parameterized_steps = [
-        FlowStep(step.tool_name, dict(step.args))
+        FlowStep(
+            step.tool_name,
+            dict(step.args),
+            purpose=step.purpose,
+            expected_outcome=step.expected_outcome,
+        )
         for step in executed_steps
     ]
     used_names = set(parameters)
@@ -162,6 +173,12 @@ def _record_value(record: Any, key: str) -> Any:
     return getattr(record, key, None)
 
 
+def _optional_text(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    return value.strip() or None
+
+
 def _tool_sequence(steps: list[FlowStep]) -> list[str]:
     return [step.tool_name for step in steps]