feat(session): add compact action to session control tool

Add the compact action to the session control tool family so a caller can
compact a session context to reduce its token footprint and surface the
applied compaction statistics (tokens/ratio/summary).

- Thread ContextCompactionOutcome through the manual compaction task so the
  finished outcome is returned instead of being discarded (unit).
- Add compact_session_with_outcome returning BitFunResult<ContextCompactionOutcome>;
  compact_session_manually delegates to it for the Desktop compatibility API.
- Extend SessionControlAction with a Compact variant and its as_str mapping.
- Allow compacting the caller own session (the sole self-mutation exception)
  while keeping owner/creator/ancestor authorization inline.
- Wire the Compact dispatch to the compact engine and return the applied stats.
- Extend the tool input schema/description and add compact validation tests.

Test: cargo check -p bitfun-core --jobs 4 EXIT 0; cargo check -p bitfun-agent-runtime --jobs 4 EXIT 0; cargo test -p bitfun-agent-runtime --features agent-runtime compact --jobs 4 (5 tests pass); cargo test -p bitfun-core --features agent-runtime session_control_tool --jobs 4 (14 tests pass incl validate_compact_*); cargo test -p bitfun-core --features agent-runtime manual_compaction --jobs 4 (6 tests pass).
AI: lightly tested (targeted cargo check + compact/session_control_tool/manual_compaction unit tests).

Author: user

src/crates/assembly/core/src/agentic/coordination/coordinator.rs

@@ -789,7 +789,7 @@ struct SessionExecutionLease {
 
 struct ManualCompactionTask {
     turn_id: String,
-    completion: oneshot::Receiver<BitFunResult<()>>,
+    completion: oneshot::Receiver<BitFunResult<ContextCompactionOutcome>>,
 }
 
 struct ManualCompactionControlGuard {
@@ -5451,7 +5451,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         remote_exec_port: Option<Arc<dyn RemoteExecPort>>,
         cancellation_token: CancellationToken,
         commit_gate: Arc<ManualCompactionCommitGate>,
-    ) -> BitFunResult<()> {
+    ) -> BitFunResult<ContextCompactionOutcome> {
         let manual_workspace_services = Self::build_workspace_services(&manual_workspace).await;
         let manual_execution_context = ExecutionContext {
             session_id: session_id.clone(),
@@ -5516,7 +5516,8 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
                     &outcome,
                     context_window,
                 )
-                .await
+                .await?;
+                Ok(outcome)
             }
             Err(err @ BitFunError::Cancelled(_)) => {
                 let error_text = err.to_string();
@@ -5584,6 +5585,17 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
     /// task used by Agent Runtime callers, then await its terminal result for
     /// the existing Desktop compatibility API.
     pub async fn compact_session_manually(&self, session_id: String) -> BitFunResult<()> {
+        self.compact_session_with_outcome(session_id)
+            .await
+            .map(|_| ())
+    }
+
+    /// Compact the active session context and return the compaction outcome
+    /// (tokens/ratio/summary) so tool callers can surface the applied result.
+    pub async fn compact_session_with_outcome(
+        &self,
+        session_id: String,
+    ) -> BitFunResult<ContextCompactionOutcome> {
         let task = self.start_manual_compaction_task(session_id, None).await?;
         task.completion.await.map_err(|_| {
             BitFunError::Service(format!(

src/crates/assembly/core/src/agentic/tools/implementations/session_control_tool.rs

@@ -104,6 +104,7 @@ impl SessionControlTool {
         match action {
             SessionControlAction::Cancel
             | SessionControlAction::Delete
+            | SessionControlAction::Compact
             | SessionControlAction::Rename => {
                 let session_id = session_id.ok_or_else(|| {
                     BitFunError::tool(format!("session_id is required for {}", action.as_str()))
@@ -274,6 +275,7 @@ Actions:
 - "create": Create a new session. You may optionally provide session_name and agent_type.
 - "cancel": Cancel the target session's currently running dialog turn. This does not delete the session or clear any queued messages that may still run later.
 - "delete": Delete an existing session by session_id.
+- "compact": Compact the target session's context to reduce its token footprint. Returns the applied compaction statistics.
 - "rename": Rename an existing session by session_id using session_name as the new title.
 - "list": List all sessions.
 
@@ -285,13 +287,13 @@ Arguments:
   - "Plan": Planning agent for clarifying requirements and producing an implementation plan before coding.
   - "Cowork": Collaborative agent for office-style work such as research, documentation, presentations, etc.
   - "DeepResearch": Research agent for systematic investigation and evidence-driven reports.
-- "session_id": Required for cancel, delete, and rename."#
+- "session_id": Required for cancel, delete, compact, and rename."#
                 .to_string(),
         )
     }
 
     fn short_description(&self) -> String {
-        "Create, list, rename, cancel, and delete persisted agent sessions.".to_string()
+        "Create, list, rename, compact, cancel, and delete persisted agent sessions.".to_string()
     }
 
     fn default_exposure(&self) -> ToolExposure {
@@ -304,7 +306,7 @@ Arguments:
             "properties": {
                 "action": {
                     "type": "string",
-                    "enum": ["create", "cancel", "delete", "rename", "list"],
+                    "enum": ["create", "cancel", "delete", "compact", "rename", "list"],
                     "description": "The session action to perform."
                 },
                 "workspace": {
@@ -313,7 +315,7 @@ Arguments:
                 },
                 "session_id": {
                     "type": "string",
-                    "description": "Required for cancel, delete, and rename."
+                    "description": "Required for cancel, delete, compact, and rename."
                 },
                 "session_name": {
                     "type": "string",
@@ -642,6 +644,113 @@ Arguments:
                     image_attachments: None,
                 }])
             }
+            SessionControlAction::Compact => {
+                let session_id = params.session_id.as_deref().ok_or_else(|| {
+                    BitFunError::tool("session_id is required for compact".to_string())
+                })?;
+                validate_session_id(session_id).map_err(BitFunError::tool)?;
+                let workspace = self
+                    .resolve_effective_workspace(
+                        SessionControlAction::Compact,
+                        Some(session_id),
+                        context,
+                        &runtime,
+                    )
+                    .await?;
+
+                // Authorization follows the owner/creator/ancestor semantics and
+                // additionally permits compacting the caller's own session.
+                let current_session_id = context.session_id.as_ref().ok_or_else(|| {
+                    BitFunError::tool(
+                        "cannot compact a session without a caller session in tool context"
+                            .to_string(),
+                    )
+                })?;
+                let session_manager = coordinator.get_session_manager();
+                let caller_is_owner = session_manager
+                    .get_session(current_session_id)
+                    .is_some_and(|session| session.created_by.is_none());
+                let is_self = current_session_id == session_id;
+                let created_by_match = session_manager
+                    .load_session_metadata(
+                        std::path::Path::new(&workspace.project_workspace),
+                        session_id,
+                    )
+                    .await
+                    .ok()
+                    .flatten()
+                    .and_then(|metadata| metadata.created_by)
+                    .is_some_and(|creator| {
+                        creator == session_control_creator_marker(current_session_id)
+                    });
+                if !caller_is_owner && !is_self && !created_by_match {
+                    let mut ancestors = Vec::new();
+                    let mut visited = std::collections::HashSet::new();
+                    visited.insert(session_id.to_string());
+                    let mut current = session_id.to_string();
+                    loop {
+                        let metadata = session_manager
+                            .load_session_metadata(
+                                std::path::Path::new(&workspace.project_workspace),
+                                &current,
+                            )
+                            .await
+                            .ok()
+                            .flatten();
+                        match metadata
+                            .and_then(|m| m.relationship.and_then(|r| r.parent_session_id))
+                        {
+                            Some(parent_id) => {
+                                if !visited.insert(parent_id.clone()) {
+                                    break;
+                                }
+                                ancestors.push(parent_id.clone());
+                                current = parent_id;
+                            }
+                            None => break,
+                        }
+                    }
+                    if !ancestors.is_empty() && !ancestors.contains(current_session_id) {
+                        return Err(BitFunError::tool(format!(
+                            "session '{current_session_id}' is not authorized to compact session '{session_id}': not a parent/ancestor and not the creator"
+                        )));
+                    }
+                }
+
+                let outcome = coordinator
+                    .compact_session_with_outcome(session_id.to_string())
+                    .await
+                    .map_err(|error| {
+                        BitFunError::tool(format!(
+                            "cannot compact session '{session_id}': {}",
+                            error
+                        ))
+                    })?;
+
+                Ok(vec![ToolResult::Result {
+                    data: json!({
+                        "success": true,
+                        "action": "compact",
+                        "workspace": workspace.display_workspace.clone(),
+                        "session_id": session_id,
+                        "applied": outcome.applied,
+                        "tokens_before": outcome.tokens_before,
+                        "tokens_after": outcome.tokens_after,
+                        "compression_ratio": outcome.compression_ratio,
+                        "duration": outcome.duration_ms,
+                        "summary_source": if outcome.has_summary {
+                            Some(outcome.summary_source)
+                        } else {
+                            None
+                        },
+                    }),
+                    result_for_assistant: Some(format!(
+                        "Compacted session '{session_id}' in workspace '{}'.",
+                        workspace.display_workspace
+                    )),
+                    image_attachments: None,
+                }])
+            }
             SessionControlAction::List => {
                 let workspace = self
                     .resolve_effective_workspace(
@@ -956,4 +1065,63 @@ mod tests {
 
         assert!(validation.result, "{:?}", validation.message);
     }
+
+    #[tokio::test]
+    async fn validate_compact_requires_session_id() {
+        let tool = SessionControlTool::new();
+
+        let validation = tool
+            .validate_input(
+                &json!({
+                    "action": "compact",
+                }),
+                Some(&empty_context()),
+            )
+            .await;
+
+        assert!(!validation.result);
+        assert_eq!(
+            validation.message.as_deref(),
+            Some("session_id is required for compact")
+        );
+    }
+
+    #[tokio::test]
+    async fn validate_compact_rejects_session_name() {
+        let tool = SessionControlTool::new();
+
+        let validation = tool
+            .validate_input(
+                &json!({
+                    "action": "compact",
+                    "session_id": "worker_1",
+                    "session_name": "should-not-be-here",
+                }),
+                Some(&empty_context()),
+            )
+            .await;
+
+        assert!(!validation.result);
+        assert_eq!(
+            validation.message.as_deref(),
+            Some("session_name is only allowed for create")
+        );
+    }
+
+    #[tokio::test]
+    async fn validate_compact_accepts_session_id() {
+        let tool = SessionControlTool::new();
+
+        let validation = tool
+            .validate_input(
+                &json!({
+                    "action": "compact",
+                    "session_id": "worker_1",
+                }),
+                Some(&empty_context()),
+            )
+            .await;
+
+        assert!(validation.result, "{:?}", validation.message);
+    }
 }

src/crates/execution/agent-runtime/src/session_control.rs

@@ -11,6 +11,7 @@ pub enum SessionControlAction {
     Cancel,
     Delete,
     List,
+    Compact,
     Rename,
 }
 
@@ -21,6 +22,7 @@ impl SessionControlAction {
             Self::Cancel => "cancel",
             Self::Delete => "delete",
             Self::List => "list",
+            Self::Compact => "compact",
             Self::Rename => "rename",
         }
     }
@@ -183,7 +185,13 @@ fn validate_mutating_action_target(
         return invalid(message);
     }
 
-    if context.current_session_id == Some(session_id) && context.has_workspace_root {
+    // Guard only depends on session-binding equivalence: if the target is the
+    // current session it is refused. `compact` is the sole exception (it may
+    // compress the current session and resident subagent workstations).
+    if !matches!(action, SessionControlAction::Compact)
+        && context.current_session_id == Some(session_id)
+        && context.has_workspace_root
+    {
         return invalid(format!(
             "cannot {} the current session from SessionControl",
             action.as_str()
@@ -226,6 +234,7 @@ pub fn validate_session_control_input(
         }
         SessionControlAction::Cancel
         | SessionControlAction::Delete
+        | SessionControlAction::Compact
         | SessionControlAction::Rename => {
             return validate_mutating_action_target(&input.action, input, context);
         }
@@ -266,6 +275,7 @@ pub fn render_session_control_tool_use_message(input: &Value) -> String {
         "create" => format!("Create session in {workspace}"),
         "cancel" => format!("Cancel active turn for session {session_id}"),
         "delete" => format!("Delete session {session_id}"),
+        "compact" => format!("Compact session {session_id}"),
         "rename" => format!("Rename session {session_id}"),
         "list" => format!("List sessions in {workspace}"),
         _ => format!("Manage sessions in {workspace}"),
@@ -443,4 +453,78 @@ mod tests {
         assert!(message.contains("new-title"));
         assert!(message.contains("/ws"));
     }
+
+    #[test]
+    fn compact_action_parses_payload_session_id() {
+        let input: SessionControlInput = serde_json::from_value(json!({
+            "action": "compact",
+            "session_id": "worker_1",
+        }))
+        .expect("compact payload must parse");
+        assert_eq!(input.action, SessionControlAction::Compact);
+        assert_eq!(input.session_id.as_deref(), Some("worker_1"));
+        assert_eq!(SessionControlAction::Compact.as_str(), "compact");
+    }
+
+    #[test]
+    fn compact_validation_requires_session_id() {
+        let input = SessionControlInput {
+            action: SessionControlAction::Compact,
+            workspace: None,
+            session_id: None,
+            session_name: None,
+            agent_type: None,
+        };
+        let result = validate_session_control_input(&input, context(None));
+        assert!(!result.result);
+        assert!(result
+            .message
+            .as_deref()
+            .unwrap_or_default()
+            .contains("session_id is required"));
+    }
+
+    #[test]
+    fn compact_validation_rejects_non_mutating_fields() {
+        let input = SessionControlInput {
+            action: SessionControlAction::Compact,
+            workspace: None,
+            session_id: Some("worker_1".to_string()),
+            session_name: Some("should not be allowed".to_string()),
+            agent_type: None,
+        };
+        let result = validate_session_control_input(&input, context(None));
+        assert!(!result.result);
+        assert_eq!(
+            result.message.as_deref(),
+            Some("session_name is only allowed for create")
+        );
+    }
+
+    #[test]
+    fn compact_validation_allows_current_session() {
+        let input = SessionControlInput {
+            action: SessionControlAction::Compact,
+            workspace: None,
+            session_id: Some("self_1".to_string()),
+            session_name: None,
+            agent_type: None,
+        };
+        let result = validate_session_control_input(&input, context(Some("self_1")));
+        assert!(
+            result.result,
+            "compact of the current session must be allowed: {:?}",
+            result.message
+        );
+    }
+
+    #[test]
+    fn compact_render_mentions_session() {
+        let rendered = render_session_control_tool_use_message(&json!({
+            "action": "compact",
+            "session_id": "worker_1",
+        }));
+        assert!(rendered.contains("Compact session"));
+        assert!(rendered.contains("worker_1"));
+    }
 }