Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

21.9 KB
Raw Blame
use crate::core::runtime::DispatchCtx;

impl ApprovalGate {
    /// Write the *terminal* status of a tool call onto its approval
    /// audit row — see [`store::record_execution`] for semantics.
    ///
    /// Logs (but does not propagate) write errors: the tool has
    /// already run, so audit-log loss should never bubble up as a
    /// tool execution failure to the agent. If durable audit storage
    /// is required for compliance, callers wire it via a stronger
    /// guarantee than this best-effort hook.
    pub fn record_execution(
        &self,
        request_id: &str,
        outcome: ExecutionOutcome,
        error: Option<&str>,
    ) {
        match store::record_execution(&self.config, request_id, outcome, error) {
            Ok(true) => tracing::debug!(
                request_id = %request_id,
                outcome = outcome.as_str(),
                "[approval::gate] recorded terminal execution"
            ),
            Ok(false) => tracing::warn!(
                request_id = %request_id,
                outcome = outcome.as_str(),
                "[approval::gate] record_execution found no matching decided row"
            ),
            Err(err) => tracing::error!(
                request_id = %request_id,
                outcome = outcome.as_str(),
                error = %err,
                "[approval::gate] record_execution write failed"
            ),
        }
    }

    /// Apply a user decision. Returns the now-decided
    /// [`PendingApproval`] row when one was found.
    pub fn decide(
        &self,
        request_id: &str,
        decision: ApprovalDecision,
    ) -> anyhow::Result<Option<PendingApproval>> {
        // Release the routing lock before acquiring the instance barrier:
        // registration holds that barrier while inserting its route.
        let scope = self.request_scope(request_id);
        match scope {
            Some(scope) => scope
                .with_open(|| self.decide_open(request_id, decision))
                .unwrap_or(Ok(None)),
            None => self.decide_open(request_id, decision),
        }
    }

    /// Commit a decision and release its waiter while the instance is still open.
    fn decide_open(
        &self,
        request_id: &str,
        decision: ApprovalDecision,
    ) -> anyhow::Result<Option<PendingApproval>> {
        if !matches!(
            decision,
            ApprovalDecision::ApproveOnce | ApprovalDecision::Deny
        ) && self
            .request_routes
            .lock()
            .get(request_id)
            .is_some_and(|route| route.forced)
        {
            anyhow::bail!("this action requires a one-time approval or denial");
        }
        let decided = self.decide_in_parked_scope(request_id, decision)?;
        if let Some(row) = &decided {
            // `ApproveAlwaysForTool` persistence (append to `autonomy.auto_approve`
            // + reload the live policy) is handled by the `approval_decide` RPC
            // handler, which is async and owns the config save+reload path. The
            // gate only resolves the parked future and emits the audit event.
            if let Some(tx) = self.take_waiter(request_id) {
                let _ = tx.send(decision);
            }
            // Routing (thread/client/tool_call_id) was recorded at park time —
            // see `intercept_audited_inner` — so a decision made after the
            // in-memory waiter already resolved (e.g. via the TTL/channel-drop
            // paths in `gate_intercept.rs`) still reports `None` here, which is
            // correct: this fn only fires for a live `decide()` call.
            let route = self.take_request_route(request_id);
            BUS.publish(DomainEvent::ApprovalDecided {
                request_id: row.request_id.clone(),
                tool_name: row.tool_name.clone(),
                decision: decision.as_str().to_string(),
                thread_id: route.as_ref().and_then(|r| r.thread_id.clone()),
                client_id: route.as_ref().and_then(|r| r.client_id.clone()),
                tool_call_id: route.and_then(|r| r.tool_call_id),
                resolution: None,
                agent_id: row.agent_id.clone(),
            });
        }
        Ok(decided)
    }

    /// Commits `decision` in the store the request was parked in when this
    /// process parked it (the parking task's storage scope, remembered on its
    /// route), else in the caller's scope — an orphan from an earlier launch has
    /// no route, so the caller's scope is where it can be looked for.
    pub(super) fn decide_in_parked_scope(
        &self,
        request_id: &str,
        decision: ApprovalDecision,
    ) -> anyhow::Result<Option<PendingApproval>> {
        let parked_in = self
            .request_routes
            .lock()
            .get(request_id)
            .and_then(|route| route.docs.clone());
        match parked_in {
            Some(docs) => store::decide_in(&docs, request_id, decision),
            None => store::decide(&self.config, request_id, decision),
        }
    }

    /// [`Self::decide`] on behalf of `agent`: refuses with
    /// [`ApprovalError::WrongAgent`] when the request was parked by any other
    /// agent (or by the process itself), so one agent cannot answer another's
    /// approval.
    pub fn decide_for_agent(
        &self,
        agent: &str,
        request_id: &str,
        decision: ApprovalDecision,
    ) -> anyhow::Result<Option<PendingApproval>> {
        let owner = match self
            .request_routes
            .lock()
            .get(request_id)
            .map(|route| route.agent_id.clone())
        {
            Some(owner) => Some(owner),
            None => store::pending_agent(&self.config, request_id)?,
        };
        if let Some(owner) = owner {
            if owner.as_deref() != Some(agent) {
                tracing::warn!(
                    request_id = %request_id,
                    agent_id = %agent,
                    owner = owner.as_deref().unwrap_or("<process>"),
                    "[approval::gate] decision refused: request belongs to another agent"
                );
                return Err(ApprovalError::WrongAgent {
                    request_id: request_id.to_string(),
                }
                .into());
            }
        }
        self.decide(request_id, decision)
    }

    /// Deny every undecided request `agent` parked, resolving its waiters.
    /// Returns how many rows were denied.
    pub fn deny_all_for_agent(
        &self,
        ctx: &DispatchCtx,
        agent: &str,
        resolution: &str,
    ) -> anyhow::Result<usize> {
        if !store::exists(&self.config) {
            return Ok(0);
        }
        let rows = store::list_pending_for_agent(ctx, &self.config, Some(agent))?;
        let mut denied = 0;
        for row in rows {
            let Some(decided) =
                self.decide_in_parked_scope(&row.request_id, ApprovalDecision::Deny)?
            else {
                continue;
            };
            denied += 1;
            if let Some(tx) = self.take_waiter(&decided.request_id) {
                let _ = tx.send(ApprovalDecision::Deny);
            }
            let route = self.take_request_route(&decided.request_id);
            if let Some(thread_key) = route.as_ref().and_then(|r| r.thread_key.as_deref()) {
                self.clear_thread_route_if_owned(thread_key, &decided.request_id);
            }
            BUS.publish(DomainEvent::ApprovalDecided {
                request_id: decided.request_id.clone(),
                tool_name: decided.tool_name.clone(),
                decision: ApprovalDecision::Deny.as_str().to_string(),
                thread_id: route.as_ref().and_then(|r| r.thread_id.clone()),
                client_id: route.as_ref().and_then(|r| r.client_id.clone()),
                tool_call_id: route.and_then(|r| r.tool_call_id),
                resolution: Some(resolution.to_string()),
                agent_id: Some(agent.to_string()),
            });
        }
        tracing::info!(
            agent_id = %agent,
            denied,
            resolution,
            "[approval::gate] denied every pending request of the agent"
        );
        Ok(denied)
    }

    /// Classify a [`Self::decide`] miss — i.e. when `decide` returned
    /// `Ok(None)` because the instance was closed or its conditional
    /// `UPDATE ... WHERE decided_at IS NULL` matched 0 rows.
    ///
    /// - [`DecideMiss::AlreadyResolved`] — the row exists but was **already
    ///   decided, lazily expired (denied), superseded, or closed for removal**.
    ///   This is the benign
    ///   double-tap / two-operator / expiry-while-live race the inline-approvals
    ///   design spec classifies as benign (TAURI-RUST-5EH).
    /// - [`DecideMiss::NeverRegistered`] — no row was ever persisted for this
    ///   request_id. That is a genuine lost registration (a core restart dropped
    ///   the parked future before persisting, or a stray id) and must stay a
    ///   Sentry signal.
    ///
    /// We disambiguate by consulting [`store::get_decision`], which returns a
    /// decision only when `decided_at IS NOT NULL` — exactly the already-resolved
    /// case (expiry writes a `Deny` decision, so expired rows report here too).
    /// A closed instance can still have an undecided row while removal takes
    /// its denial snapshot; this is also a benign refusal. If the lookup itself
    /// errors we conservatively keep
    /// the event visible (`NeverRegistered`) rather than silently demoting.
    pub fn classify_decide_miss(&self, request_id: &str) -> DecideMiss {
        if self
            .request_scope(request_id)
            .is_some_and(|scope| scope.is_closed())
        {
            return DecideMiss::AlreadyResolved;
        }
        match store::get_decision(&self.config, request_id) {
            Ok(Some(_)) => DecideMiss::AlreadyResolved,
            Ok(None) => DecideMiss::NeverRegistered,
            Err(err) => {
                tracing::warn!(
                    request_id = %request_id,
                    error = %err,
                    "[approval::gate] classify_decide_miss: get_decision failed; treating as never-registered (keep visible)"
                );
                DecideMiss::NeverRegistered
            }
        }
    }

    /// List all undecided rows, including orphans from prior launches.
    /// Orphan rows have no live parked future so a `decide` on them
    /// updates the DB but cannot resume an action — see [`store::list_pending`].
    pub fn list_pending(&self) -> anyhow::Result<Vec<PendingApproval>> {
        store::list_pending(&self.config)
    }

    /// [`Self::list_pending`] narrowed to `agent`'s rows; `None` lists the
    /// process's own rows.
    pub fn list_pending_for_agent(
        &self,
        ctx: &DispatchCtx,
        agent: Option<&str>,
    ) -> anyhow::Result<Vec<PendingApproval>> {
        store::list_pending_for_agent(ctx, &self.config, agent)
    }

    /// List recently decided rows for durable audit views.
    pub fn list_recent_decisions(
        &self,
        limit: usize,
    ) -> anyhow::Result<Vec<super::types::ApprovalAuditEntry>> {
        store::list_recent_decisions(&self.config, limit)
    }

    /// List undecided rows correlated with a specific flow run (issue
    /// flow-approval-surface, PR2) — lets a dedicated Workflows review
    /// surface fetch just the gates blocking one run instead of filtering
    /// [`Self::list_pending`] client-side.
    pub fn list_pending_for_flow_run(
        &self,
        flow_id: &str,
        run_id: &str,
    ) -> anyhow::Result<Vec<PendingApproval>> {
        store::list_pending_for_flow_run(&self.config, flow_id, run_id)
    }

    /// Grant "approve always for this flow" trust to `(flow_id, tool_name)`.
    /// Called by the `approval_decide` RPC handler after an
    /// [`ApprovalDecision::ApproveAlwaysForFlow`] decides a flow-origin row —
    /// mirrors the RPC-owns-persistence split documented on
    /// [`Self::decide`] for `ApproveAlwaysForTool`.
    pub fn insert_flow_trust(&self, flow_id: &str, tool_name: &str) -> anyhow::Result<()> {
        store::insert_flow_trust(&self.config, flow_id, tool_name)
    }

    /// Whether `(flow_id, tool_name)` currently holds "approve always for
    /// this flow" trust. Exposed for tests and diagnostics; `intercept_audited`
    /// consults [`store::is_flow_tool_trusted`] directly.
    pub fn is_flow_tool_trusted(&self, flow_id: &str, tool_name: &str) -> anyhow::Result<bool> {
        store::is_flow_tool_trusted(&self.config, flow_id, tool_name)
    }

    /// Every `tool_name` currently trusted for `flow_id`, sorted. Consumed by
    /// `flows_approval_manifest` to diff the graph's required permissions
    /// against grants that already exist (re-save asks only for what's new).
    pub fn list_flow_trust(&self, flow_id: &str) -> anyhow::Result<Vec<String>> {
        store::list_flow_trust(&self.config, flow_id)
    }

    /// Revoke flow trust: all grants for `flow_id` when `tool_names` is
    /// `None` (flow deletion cleanup), or only the named grants. Returns the
    /// number of rows removed.
    pub fn delete_flow_trust(
        &self,
        flow_id: &str,
        tool_names: Option<&[String]>,
    ) -> anyhow::Result<usize> {
        store::delete_flow_trust(&self.config, flow_id, tool_names)
    }

    /// Write the durable audit record for one save-time pre-authorization
    /// grant (a born-decided `approve_always_for_flow` row) so blanket
    /// grants stay inspectable in Settings → Approval history.
    pub fn record_flow_preauthorization(
        &self,
        flow_id: &str,
        tool_name: &str,
    ) -> anyhow::Result<()> {
        store::record_flow_preauthorization(&self.config, flow_id, tool_name, &self.session_id)
    }

    /// Return the session id this gate was installed with (used by
    /// RPC handlers for diagnostics).
    pub fn session_id(&self) -> &str {
        &self.session_id
    }

    /// Clone the instance barrier without retaining the routing-map lock.
    fn request_scope(&self, request_id: &str) -> Option<Arc<super::ApprovalScope>> {
        self.request_routes
            .lock()
            .get(request_id)
            .and_then(|route| route.approval_scope.clone())
    }

    fn take_waiter(&self, request_id: &str) -> Option<oneshot::Sender<ApprovalDecision>> {
        let mut waiters = self.waiters.lock();
        waiters.remove(request_id)
    }

    /// Record the routing correlation for a newly-parked request. Called at
    /// park time in `intercept_audited_inner`, alongside the `thread_to_request`
    /// insert.
    fn insert_request_route(&self, request_id: &str, route: RequestRoute) {
        self.request_routes
            .lock()
            .insert(request_id.to_string(), route);
    }

    /// Remove and return the routing correlation for `request_id`, if any.
    /// Consumed exactly once per request — by whichever path resolves the
    /// decision first (`decide`, a TTL timeout, or a dropped channel).
    fn take_request_route(&self, request_id: &str) -> Option<RequestRoute> {
        self.request_routes.lock().remove(request_id)
    }

    fn evict_waiter(&self, request_id: &str) {
        let mut waiters = self.waiters.lock();
        waiters.remove(request_id);
    }

    /// The request_id of the approval currently parked on `thread_id` by the
    /// ambient tenant (SaaS profile and/or embedded agent), if any. Used by
    /// the web channel to route an inbound yes/no reply to a decision.
    pub fn pending_for_thread(&self, thread_id: &str) -> Option<String> {
        self.pending_for_tenant_thread(&super::gate::current_route_tenant(), thread_id)
    }

    /// The request_id `agent` (`None`: the process) has parked on
    /// `thread_id` outside any SaaS profile, if any.
    pub fn pending_for_agent_thread(&self, agent: Option<&str>, thread_id: &str) -> Option<String> {
        let tenant = crate::core::runtime::Tenant {
            profile: None,
            agent: agent.map(str::to_owned),
        };
        self.pending_for_tenant_thread(&tenant, thread_id)
    }

    /// The request_id `tenant` has parked on `thread_id`, if any.
    pub fn pending_for_tenant_thread(
        &self,
        tenant: &crate::core::runtime::Tenant,
        thread_id: &str,
    ) -> Option<String> {
        self.thread_to_request
            .lock()
            .get(&thread_route_key(tenant, thread_id))
            .cloned()
    }

    /// The full pending row parked on `thread_id`, if any.
    ///
    /// [`Self::pending_for_thread`] answers *which* request is parked; this
    /// answers *what it is*, which is what a UI needs to rebuild the approval
    /// card from scratch.
    ///
    /// The card reaches the UI as ONE fire-and-forget socket emit. If that emit
    /// misses — the addressed client's room is empty because the page reloaded,
    /// a rejoining socket was not yet in the thread room, or the bridge dropped
    /// the frame on broadcast lag — nothing re-sends it. The request stays
    /// parked server-side and the user is left with no card and no way to act,
    /// which is the whole failure: durable state delivered as an ephemeral
    /// event, with no way to reconcile the two. This lookup is that
    /// reconciliation, so a socket (re)joining a thread can be handed whatever
    /// is parked on it.
    ///
    /// Reads the routing map first and the durable rows second, so a request
    /// decided between the two reads simply falls out as `None` rather than
    /// replaying a card the user has already answered.
    pub fn parked_request_for_thread(&self, thread_id: &str) -> Option<PendingApproval> {
        let request_id = self.pending_for_thread(thread_id)?;
        let row = self
            .list_pending()
            .ok()?
            .into_iter()
            .find(|row| row.request_id == request_id)?;
        // Re-read the route before answering. `list_pending` is a store read and
        // runs without the route lock held, so between the two the mapping can
        // be cleared by a caller-bound abandon or overwritten by a replacement
        // turn parking a new approval on the same thread (#4774's scenario).
        // Either leaves this row pending while it is no longer the thread's, and
        // the only caller replays what it gets straight onto the user's screen —
        // so a stale row here is a stale approval card, not a harmless read.
        //
        // Narrowing, not closing: the row itself could still be decided after
        // this check. That is the pre-existing fire-and-forget property of the
        // replay path, and `request_id` idempotency on the client is what covers
        // it; this only stops the lookup from *starting* with a row it can
        // already tell is not the thread's (#6212 review).
        self.pending_for_thread(thread_id)
            .is_some_and(|current| current == request_id)
            .then_some(row)
    }

    /// Every approval still parked on `thread_id` by the ambient context's
    /// agent, oldest first.
    ///
    /// [`Self::parked_request_for_thread`] follows the single thread route,
    /// which holds only the newest park. Several async-delegated sub-agents can
    /// park on the same parent thread at once; each keeps its own waiter and
    /// [`RequestRoute`], so replay reads those instead and a rejoining client
    /// can rebuild every card, not only the last one raised.
    pub fn parked_requests_for_thread(&self, thread_id: &str) -> Vec<PendingApproval> {
        let agent = crate::core::runtime::agent_scope::current_agent_id();
        let parked_here = |route: &RequestRoute| {
            route.thread_id.as_deref() == Some(thread_id)
                && route.agent_id.as_deref() == agent.as_deref()
        };
        let ids: std::collections::HashSet<String> = self
            .request_routes
            .lock()
            .iter()
            .filter(|(_, route)| parked_here(route))
            .map(|(id, _)| id.clone())
            .collect();
        if ids.is_empty() {
            return Vec::new();
        }
        let mut rows: Vec<PendingApproval> = match self.list_pending() {
            Ok(rows) => rows
                .into_iter()
                .filter(|row| ids.contains(&row.request_id))
                .collect(),
            Err(error) => {
                tracing::warn!(
                    error = %error,
                    "[approval::gate] parked_requests_for_thread: store read failed"
                );
                return Vec::new();
            }
        };
        // Re-check after the unlocked store read, as `parked_request_for_thread`
        // does: a request decided in between must not be replayed.
        let routes = self.request_routes.lock();
        rows.retain(|row| routes.get(&row.request_id).is_some_and(parked_here));
        rows
    }

    /// Whether the parked `request_id` was routed to its chat thread from a
    /// detached task (an async-delegated sub-agent), so the replayed card keeps
    /// the live event's `detached` flag. `false` for an unknown request.
    pub fn request_is_detached(&self, request_id: &str) -> bool {
        self.request_routes
            .lock()
            .get(request_id)
            .is_some_and(|route| route.detached)
    }

    /// Drop the thread → request mapping when it still belongs to this request.
    fn clear_thread(&self, thread_key: &Option<String>, request_id: &str) {
        if let Some(key) = thread_key {
            self.clear_thread_route_if_owned(key, request_id);
        }
    }

    /// Drop the thread → request mapping **only if** it still points at
    /// `request_id`. Used by [`WaiterGuard::drop`] on external teardown, where a
    /// replacement turn may have already parked a new approval on the same
    /// thread and overwritten the entry; clearing unconditionally would delete
    /// the *new* request's routing (#4774).
    fn clear_thread_route_if_owned(&self, thread_key: &str, request_id: &str) {
        let mut map = self.thread_to_request.lock();
        if map.get(thread_key).is_some_and(|rid| rid == request_id) {
            map.remove(thread_key);
        }
    }
}