Grok Build
从源码学会它怎么工作

  120  pub(super) async fn run_session(
  121      session: Arc<SessionActor>,
  122      mut cmd_rx: mpsc::UnboundedReceiver<SessionCommand>,
  123      mut chat_state_event_rx: mpsc::UnboundedReceiver<xai_chat_state::ChatStateEvent>,
  124      mut event_rx: mpsc::UnboundedReceiver<SessionEvent>,
  125      fs_notify_config: Option<ClientFsConfig>,
  126      codebase_indexes: std::sync::Arc<parking_lot::Mutex<CodebaseIndexManager>>,
  127      index_root: std::path::PathBuf,
  128      fs_watch_caps: fs_watch::FsWatchCapabilities,
  129  ) {
  130      let (completion_tx, mut completion_rx) =
  131          mpsc::unbounded_channel::<(String, PromptTurnResult)>();
  132      tracing::debug!("fs_notify_config: {:?}", fs_notify_config);
  133      let mut replay_buffer = ReplayBuffer::new(session.buffering_settings.clone());
  134      let event_tx_for_flush_timer = session.event_tx.clone();
  135      let buffering_flush_interval = replay_buffer.max_wait_duration_ms();
  136      if let Some(buffering_flush_interval) = buffering_flush_interval {
  137          tokio::task::spawn_local(async move {
  138              let mut interval = tokio::time::interval(Duration::from_millis(std::cmp::max(
  139                  20,
  140                  buffering_flush_interval * 2,
  141              )));
  142              loop {
  143                  interval.tick().await;
  144                  let _ =
      … 28 lines omitted; exact range 120–183 …
  173              index_root.clone(),
  174          );
  175          tracing::debug!(?fs_watch_caps, "fs-notify: spawning");
  176          Some(fs_watch::spawn(fs_watch::FsWatchPlan::build(
  177              fs_watch_caps,
  178              deps,
  179          )))
  180      } else {
  181          tracing::debug!("fs-notify: skipped (no consumers)");
  182          None
  183      };

  355      /// Prepare → dispatch → post-flight. Caller owns the outer tail flush.
  356      async fn execute_tool_calls_batch(
  357          &self,
  358          tool_calls: Vec<crate::sampling::types::ToolCallResponse>,
  359          deferred_followups: &mut Vec<ConversationItem>,
  360          final_result: &mut Option<ToolLoop>,
  361      ) -> Result<(), acp::Error> {
  362          let mut approved: Vec<PreparedToolCall> = Vec::new();
  363          for call in tool_calls.into_iter() {
  364              if final_result.is_some() {
  365                  let message = match &*final_result {
  366                      Some(ToolLoop::PermissionReject { .. }) => {
  367                          format!(
  368                              "Tool execution cancelled due to earlier permission rejection for tool `{}`",
  369                              call.function.name
  370                          )
  371                      }
  372                      Some(ToolLoop::Cancelled) => {
  373                          format!(
  374                              "Tool execution cancelled due to earlier user cancellation for tool `{}`",
  375                              call.function.name
  376                          )
  377                      }
  378                      Some(ToolLoop::FollowupMessage(_)) => {
  379                          format!(
      … 59 lines omitted; exact range 355–449 …
  439                          tool_loop,
  440                          ToolLoop::PermissionReject { .. }
  441                              | ToolLoop::Cancelled
  442                              | ToolLoop::FollowupMessage(_)
  443                      ) && final_result.is_none()
  444                      {
  445                          *final_result = Some(tool_loop);
  446                      }
  447                  }
  448              }
  449          }

  878          let args_str = crate::session::helpers::tool_input_parsing::normalize_empty_arguments(
  879              &call.function.arguments,
  880          );
  881          let parse_result = serde_json::from_str::<serde_json::Value>(args_str);
  882          let mut concatenated_json_count: usize = 0;
  883          let raw_input = match &parse_result {
  884              Ok(value) => value.clone(),
  885              Err(e) => {
  886                  if let Some(objects) = crate::session::helpers::tool_input_parsing::try_extract_concatenated_json_objects(
  887                      &call.function.arguments,
  888                  ) {
  889                      let total_count = objects.len();
  890                      if objects.is_empty() {
  891                          json!({ "raw": call.function.arguments.clone() })
  892                      } else {
  893                          let best_match = objects[0].clone();
  894                          let mut selected_index = 0;
  895                          let mut matched_tool = false;
  896                          let bridge = self.agent.borrow().tool_bridge().clone();
  897                          for (idx, obj) in objects.iter().enumerate() {
  898                              if bridge
  899                                  .try_parse(&call.function.name, obj.clone())
  900                                  .await
  901                                  .is_ok()
  902                              {
      … 37 lines omitted; exact range 878–950 …
  940                  self.handle_tool_parse_error(
  941                      &tool_call_id,
  942                      &call.id,
  943                      &call.function.name,
  944                      err,
  945                      &call.function.arguments,
  946                      &model_id_str,
  947                  )
  948                  .await?;
  949                  return Ok(Err(ToolLoop::ToolParsingError));
  950              }

  103      match field {
  104          Some(PathOrInline::Path(p)) => {
  105              let resolved = plugin_root.join(p);
  106              if !is_path_contained(&resolved, plugin_root) {
  107                  tracing::warn!(
  108                      path = %resolved.display(),
  109                      plugin_root = %plugin_root.display(),
  110                      "{label} path escapes plugin root; skipping"
  111                  );
  112                  return None;
  113              }
  114              resolved.is_file().then_some(resolved)
  115          }
  116          Some(PathOrInline::Inline(_)) => None,
  117          None => {
  118              let default = plugin_root.join(default_file);
  119              default.is_file().then_some(default)
  120          }
  121      }
  122  }
  123  
  124  /// A value that can be either a file path (string) or an inline JSON object.
  125  #[derive(Debug, Clone, Deserialize)]
  126  #[serde(untagged)]
  127  pub enum PathOrInline {
      … 32 lines omitted; exact range 103–170 …
  160      #[serde(default)]
  161      pub commands: Option<PathOrPaths>,
  162      #[serde(default)]
  163      pub agents: Option<PathOrPaths>,
  164      #[serde(default)]
  165      pub hooks: Option<PathOrInline>,
  166      #[serde(default)]
  167      pub mcp_servers: Option<PathOrInline>,
  168      #[serde(default)]
  169      pub lsp_servers: Option<PathOrInline>,
  170  }

    3  //! This module contains all compaction-related methods: manual `/compact`,
    4  //! auto-compact threshold checks, inline auto-compact with auto-continue,
    5  //! error-recovery compaction, preflight overflow detection, and checkpoint
    6  //! persistence. These methods form a second `impl SessionActor` block that
    7  //! lives alongside the primary one in `acp_session.rs`.
    8  use super::SessionActor;
    9  use super::is_project_instructions;
   10  use crate::remote::DEFAULT_CONTEXT_WINDOW;
   11  use crate::session::compaction_config::{
   12      AsyncCompactionCache, SUPPRESS_AUTH, SUPPRESS_NONE, SUPPRESS_STICKY, SUPPRESS_TURN,
   13      SUPPRESS_UNTIL_SUCCESS,
   14  };
   15  use crate::session::helpers::CompactionStateContext;
   16  use crate::session::helpers::compaction_context::CompactionInputs;
   17  use crate::session::helpers::compaction_context::to_system_reminder;
   18  use crate::session::helpers::session_compact::{
   19      CompactOutput, CompactionOutcome, build_compaction_chat_history,
   20      build_two_pass_compaction_prompt, generate_session_compact, is_context_length_error,
   21  };
   22  use crate::session::persistence::PersistenceMsg;
   23  use crate::session::two_pass::{
   24      TWO_PASS_DEFAULT_SPLIT_FRACTION, build_two_pass_pass1_history, build_two_pass_pass2_history,
   25      note_for_two_pass_pass2, split_conversation_for_two_pass,
   26  };
   27  use agent_client_protocol as acp;
   28  use std::sync::Arc;
   29  use xai_chat_state::compaction_utils::{
   30      CompactedHistoryInput, CompactionAttempt, build_compacted_history, is_degenerate_summary,
   31      prepare_conversation_for_verbatim_summarization, sanitize_compacted_history,
   32      validate_compacted_history,
   33  };
   34  use xai_grok_sampling_types::{ApiBackend, ConversationItem};
   35  /// Default percentage points below the auto-compact threshold at which prefire

 1282          let generate_session_compact = compact_output.content.clone();
 1283          let user_message_prefix = self.build_user_message_prefix().await;
 1284          let conversation = self.chat_state_handle.get_conversation().await;
 1285          let (discovered_agents_md, all_skills_for_compaction, _agent_edited_paths, state_context) =
 1286              if use_short_prompt {
 1287                  let empty_edited: std::collections::BTreeSet<String> = Default::default();
 1288                  let ctx =
 1289                      CompactionStateContext::build(&conversation, CompactionInputs::default()).await;
 1290                  (Vec::<std::path::PathBuf>::new(), vec![], empty_edited, ctx)
 1291              } else {
 1292                  let agents_md: Vec<std::path::PathBuf> = self
 1293                      .agent
 1294                      .borrow()
 1295                      .tool_bridge()
 1296                      .agents_md_reminded_paths()
 1297                      .await
 1298                      .into_iter()
 1299                      .collect();
 1300                  let bridge_for_skills = self.agent.borrow().tool_bridge().clone();
 1301                  let skills = bridge_for_skills.slash_skills().await;
 1302                  let edited_paths = self.chat_state_handle.get_agent_edited_paths().await;
 1303                  let ctx = {
 1304                      let bridge_tasks = self
 1305                          .agent
 1306                          .borrow()
      … 143 lines omitted; exact range 1282–1460 …
 1450                              session_id = %self.session_info.id.0,
 1451                              poll_resolved = poll.is_some(),
 1452                              cancel_resolved = cancel.is_some(),
 1453                              "could not resolve subagent tool names, \
 1454                               omitting subagent reminder from compacted conversation"
 1455                          );
 1456                          None
 1457                      }
 1458                  }
 1459              };
 1460          use crate::session::helpers::compaction_context::McpToolNames;

  157  /// Verdict for a tool call evaluated against the plan-mode edit gate.
  158  #[derive(Debug, Clone, Copy, PartialEq, Eq)]
  159  pub(super) enum PlanEditGate {
  160      /// Execute normally (plan mode inactive, not an edit, or allowed target).
  161      Allow,
  162      /// Grok-toolset edit outside the plan file (plan-file-only rule).
  163      RejectNonPlanFile,
  164  }
  165  /// Gate edit-class tool calls while plan mode is active.
  166  ///
  167  /// Plan mode is read-only **in every permission mode, including
  168  /// always-approve**: the permission manager's YOLO fast path deliberately
  169  /// knows nothing about plan mode, so this gate — not the permission system —
  170  /// is what enforces it. Two rules, matching the two toolsets' contracts:
  171  ///
  172  /// - **Compat-toolset `Write`/`StrReplace`**: any markdown
  173  ///   file is editable in plan mode (plan docs are written with these
  174  ///   same tools); everything else is rejected. Pre-existing behavior.
  175  /// - **Compat-toolset `Delete`** is **not** on the markdown carve-out: it maps to
  176  ///   `AccessKind::Edit` and is plan-file-only (same as grok edits). Deleting
  177  ///   an arbitrary `.md` in plan mode must not pass.
  178  /// - **Every other edit tool** (`AccessKind::Edit`) is restricted to the plan
  179  ///   file itself, via the same predicate that auto-approves plan-file edits
  180  ///   ([`PlanModeTracker::should_auto_approve_edit`]) so the gate and the
  181  ///   permission bypass can never disagree.
      … 13 lines omitted; exact range 157–205 …
  195      if !tracker.is_active() {
  196          return PlanEditGate::Allow;
  197      }
  198      let _ = tool_input;
  199      match access_kind {
  200          AccessKind::Edit(path) if !tracker.should_auto_approve_edit(Path::new(path)) => {
  201              PlanEditGate::RejectNonPlanFile
  202          }
  203          _ => PlanEditGate::Allow,
  204      }
  205  }

 1035          let plan_file_auto_approve = if let AccessKind::Edit(ref path) = access_kind {
 1036              self.plan_mode
 1037                  .lock()
 1038                  .should_auto_approve_edit(std::path::Path::new(path))
 1039          } else {
 1040              false
 1041          };
 1042          if plan_file_auto_approve {
 1043              tracing::info_span!(
 1044                  "tool.decision",
 1045                  tool_name = %call.function.name,
 1046                  tool_use_id = %call.id,
 1047                  decision = "allow",
 1048                  source = "config",
 1049                  wait_ms = 0_i64,
 1050              )
 1051              .in_scope(|| {});
 1052          }
 1053          if !plan_file_auto_approve {
 1054              let (perm_title, perm_kind, perm_raw_input) = tool_call_display
 1055                  .as_ref()
 1056                  .map(|(t, k, r)| (Some(t.clone()), Some(*k), Some(r.clone())))
 1057                  .unwrap_or((None, None, None));
 1058              let tool_call_update = acp::ToolCallUpdate::new(
 1059                  tool_call_id.clone(),
      … 32 lines omitted; exact range 1035–1102 …
 1092                  Some(self.session_id_string())
 1093              } else {
 1094                  None
 1095              };
 1096              let perm_mode = if self.permissions.is_yolo_mode() {
 1097                  xai_grok_telemetry::enums::PermissionMode::AlwaysApprove
 1098              } else if self.permissions.is_auto_mode() {
 1099                  xai_grok_telemetry::enums::PermissionMode::Auto
 1100              } else {
 1101                  xai_grok_telemetry::enums::PermissionMode::Ask
 1102              };

  977          let dispatch_target_name = tool_input.dispatch_target_name();
  978          let resolved_tool_name = dispatch_target_name
  979              .clone()
  980              .unwrap_or_else(|| call.function.name.clone());
  981          if self.hook_event_active(xai_grok_hooks::event::HookEventName::PreToolUse) {
  982              let (hook_tool_input, hook_tool_input_truncated) =
  983                  xai_grok_hooks::event::truncate_payload(raw_input.clone());
  984              let envelope = self.make_hook_envelope(
  985                  xai_grok_hooks::event::HookEventName::PreToolUse,
  986                  None,
  987                  xai_grok_hooks::event::HookPayload::PreToolUse {
  988                      tool_name: resolved_tool_name.clone(),
  989                      tool_use_id: call.id.clone(),
  990                      tool_input: hook_tool_input,
  991                      tool_input_truncated: hook_tool_input_truncated,
  992                      subagent_type: self.subagent_type_label(),
  993                  },
  994              );
  995              let hook_registry_snapshot = self.hook_registry.borrow().clone();
  996              if let Some(registry) = hook_registry_snapshot {
  997                  let ctx = self.hook_run_ctx();
  998                  let pre_result =
  999                      xai_grok_hooks::dispatcher::dispatch_pre_tool_use(&registry, &envelope, &ctx)
 1000                          .await;
 1001                  self.send_hook_execution(
      … 22 lines omitted; exact range 977–1034 …
 1024                          )
 1025                          .await?));
 1026                  }
 1027              }
 1028              if let Some(denied) = self
 1029                  .run_pre_tool_use_client_hook(&call, &tool_call_id, &envelope)
 1030                  .await?
 1031              {
 1032                  return Ok(Err(denied));
 1033              }
 1034          }

    8  //! OS-level sandboxing for Grok Build via [nono](https://crates.io/crates/nono).
    9  //!
   10  //! Applied once at process startup. Covers in-process `tokio::fs` calls
   11  //! and child processes. Network is left open at the process level (agent
   12  //! needs LLM API); child network is blocked per-subprocess via seccomp.
   13  //!
   14  //! The `enforce` feature (on by default) pulls in `nono` for
   15  //! kernel-enforced sandboxing (Landlock/Seatbelt). When disabled, the
   16  //! crate still provides lightweight helpers (`log_violation`,
   17  //! `should_restrict_child_network`, `child_net`) that compile on all
   18  //! targets including musl.

  107  /// The non-`off` sandbox profile this process was **requested** with, if any.
  108  ///
  109  /// This is the configured request, not a report that enforcement succeeded —
  110  /// `is_active()` can be false while the process is still confined (e.g. some
  111  /// Linux bwrap paths), and a requested-but-unapplied profile already warns the
  112  /// user. Keying on the request is the fail-closed choice.
  113  pub fn requested_confinement_profile() -> Option<&'static str> {
  114      configured_profile_name().filter(|name| profile_confines(name))
  115  }
  116  fn profile_confines(name: &str) -> bool {
  117      name.parse::<ProfileName>()
  118          .is_ok_and(|profile| profile != ProfileName::Off)
  119  }
  120  /// Whether the sandbox was successfully applied to this process.
  121  pub fn is_active() -> bool {
  122      SANDBOX.get().is_some_and(|s| s.applied)
  123  }
  124  /// The active sandbox profile name, or `None` if sandbox is not applied.
  125  pub fn profile_name() -> Option<&'static str> {
  126      SANDBOX
  127          .get()
  128          .filter(|s| s.applied)
  129          .map(|s| s.profile.as_str())

    8  //! OS-level sandboxing for Grok Build via [nono](https://crates.io/crates/nono).
    9  //!
   10  //! Applied once at process startup. Covers in-process `tokio::fs` calls
   11  //! and child processes. Network is left open at the process level (agent
   12  //! needs LLM API); child network is blocked per-subprocess via seccomp.
   13  //!
   14  //! The `enforce` feature (on by default) pulls in `nono` for
   15  //! kernel-enforced sandboxing (Landlock/Seatbelt). When disabled, the
   16  //! crate still provides lightweight helpers (`log_violation`,
   17  //! `should_restrict_child_network`, `child_net`) that compile on all
   18  //! targets including musl.

  113  /// Load sandbox config from `~/.grok/sandbox.toml` and `.grok/sandbox.toml`.
  114  ///
  115  /// Project config may **add** new profile names only. It cannot redefine a
  116  /// name already present in the global config — last-write-wins would let a
  117  /// malicious workspace hollow out a user/enterprise custom profile (e.g.
  118  /// empty `deny` / broad `read_write`) while keeping the trusted name.
  119  pub fn load_sandbox_config(workspace: &Path) -> SandboxConfig {
  120      let mut config = SandboxConfig::default();
  121  
  122      // Global config: ~/.grok/sandbox.toml
  123      let global_path = grok_home().join("sandbox.toml");
  124      if let Some(global) = load_config_file(&global_path) {
  125          config = global;
  126      }
  127  
  128      // Project config: <workspace>/.grok/sandbox.toml (additive only)
  129      let project_path = workspace.join(".grok").join("sandbox.toml");
  130      if let Some(project) = load_config_file(&project_path) {
  131          merge_project_profiles(&mut config, project);
  132      }
  133  
  134      config
  135  }
  136  
  137  pub fn sandbox_profile_conflicts(workspace: &Path) -> Vec<String> {
      … 19 lines omitted; exact range 113–167 …
  157      names.sort_unstable();
  158      names
  159  }
  160  
  161  /// Merge project profiles into `config`. Names already defined globally are
  162  /// ignored so a workspace cannot replace a global custom profile's policy.
  163  fn merge_project_profiles(config: &mut SandboxConfig, project: SandboxConfig) {
  164      for (name, profile) in project.profiles {
  165          config.profiles.entry(name).or_insert(profile);
  166      }
  167  }

    1  //! AGENTS.md / Claude.md / rules directory discovery and loading.
    2  //!
    3  //! Searches from cwd to repo root, plus `~/.grok/`. Also discovers
    4  //! `*.md` files in rules directories: vendor-prefixed `.grok/rules/`,
    5  //! `.claude/rules/`, and `.cursor/rules/` in project directories, and a
    6  //! plain `rules/` directly under the vendor-qualified home-scope roots
    7  //! (`~/.grok/rules/`, `~/.claude/rules/`, `~/.cursor/rules/`).

   80  /// Agent-specific inputs for system prompt rendering.
   81  ///
   82  /// Serializable (JSON/YAML) so users can dump it and inspect fields.
   83  /// Rendering goes through `ToolBridge::render_prompt()`.
   84  #[derive(Debug, Clone, Serialize, Deserialize)]
   85  pub struct PromptContext {
   86      /// Schema version for forward-compatible persistence.
   87      pub version: u32,
   88      /// Which prompt mode produced this context.
   89      pub prompt_mode: PromptMode,
   90      /// Whether this is a primary (parent) or subagent (child) session.
   91      /// Controls base template choice and catalog section rendering.
   92      #[serde(default)]
   93      pub audience: PromptAudience,
   94      /// Custom body: appended after base template (Extend) or the entire
   95      /// prompt (Full). `None` = base template only.
   96      #[serde(skip_serializing_if = "Option::is_none")]
   97      pub prompt_body: Option<String>,
   98      /// Which base template to use for `Extend` mode.
   99      /// `TemplateOverride::None` = standard base/subagent template.
  100      /// `TemplateOverride::Codex` = apply-patch profile template (decrypted on demand).
  101      /// `TemplateOverride::Custom` = caller-provided template string.
  102      #[serde(default, skip_serializing_if = "is_template_override_none")]
  103      pub system_prompt: TemplateOverride,
  104      /// AGENTS.md files discovered during build, in precedence order
      … 37 lines omitted; exact range 80–152 …
  142      #[serde(default, skip_serializing_if = "Option::is_none")]
  143      pub current_date: Option<String>,
  144      /// Whether the agent is running in a non-interactive (headless / SDK /
  145      /// stdio / generic-ACP).
  146      #[serde(default)]
  147      pub is_non_interactive: bool,
  148      /// Identity in the primary grok-build system prompt (`You are <label>…`).
  149      /// Not the UI picker name. Defaults to [`DEFAULT_SYSTEM_PROMPT_LABEL`].
  150      #[serde(default = "default_system_prompt_label")]
  151      pub system_prompt_label: String,
  152  }

  811          {
  812              let _span = tracing::info_span!("tool.register").entered();
  813              let early_raw_input =
  814                  serde_json::from_str::<serde_json::Value>(&call.function.arguments).ok();
  815              let subagent_background = matches!(
  816                  call.function.name.as_str(),
  817                  "task" | "Task" | "spawn_subagent"
  818              )
  819              .then(|| {
  820                  early_raw_input
  821                      .as_ref()
  822                      .and_then(|v| v.get("run_in_background").or_else(|| v.get("background")))
  823                      .and_then(serde_json::Value::as_bool)
  824                      .unwrap_or(true)
  825              });
  826              let mut meta = self.stamp_tool_meta(None, &call.function.name, None);
  827              if let Some(bg) = subagent_background {
  828                  meta.get_or_insert_with(serde_json::Map::new).insert(
  829                      "subagentBackground".to_string(),
  830                      serde_json::Value::Bool(bg),
  831                  );
  832              }
  833              self.send_update(
  834                  acp::SessionUpdate::ToolCall(
  835                      acp::ToolCall::new(tool_call_id.clone(), call.function.name.clone())
  836                          .kind(acp::ToolKind::Other)
  837                          .status(acp::ToolCallStatus::Pending)
  838                          .raw_input(early_raw_input)
  839                          .meta(meta),

  392              self.emit_event(crate::session::events::Event::ToolStarted {
  393                  tool_name: call.function.name.clone(),
  394              });
  395              self.observability_bridge
  396                  .emit(
  397                      xai_tool_protocol::session_event::SessionEvent::ToolCallStarted {
  398                          tool_call_id: call.id.clone(),
  399                          tool_name: call.function.name.clone(),
  400                          turn_number: self.current_turn_number.get(),
  401                      },
  402                  )
  403                  .await;
  404              let call_name = call.function.name.clone();
  405              match self.prepare_tool_call(call, deferred_followups).await? {
  406                  Ok(prepared) => approved.push(prepared),
  407                  Err(tool_loop) => {
  408                      self.events.tool_finished();
  409                      if let Some((server, tool)) =
  410                          crate::session::mcp_servers::parse_mcp_tool_name(&call_name)
  411                      {
  412                          let error_reason = match &tool_loop {
  413                              ToolLoop::PermissionReject { reason, .. } => reason.clone(),
  414                              ToolLoop::Cancelled => "cancelled".to_string(),
  415                              ToolLoop::FollowupMessage(_) => "followup".to_string(),
  416                              ToolLoop::HookDenied { hook_name, .. } => {
      … 9 lines omitted; exact range 392–436 …
  426                                  server,
  427                                  crate::session::mcp_servers::MCP_TOOL_NAME_DELIMITER,
  428                                  tool
  429                              ),
  430                              duration_ms: 0,
  431                              success: false,
  432                              is_timeout: false,
  433                              error: Some(error_reason),
  434                              reconnect_attempted: false,
  435                              auth_retry_attempted: false,
  436                          });