Approval Workflow Implementation
The approval workflow is integrated into the agent run lifecycle within thepalyrad daemon. When a tool proposal is evaluated, the system determines if the action requires manual intervention.
Tool Proposal Security Evaluation
Before execution, every tool call is passed throughevaluate_tool_proposal_security crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-134. This function returns a ToolProposalSecurityEvaluation containing:
skill_gate_decision: The result of policy evaluation.proposal_approval_required: A boolean indicating if the specific tool/input combination requires human review.approval_subject_id: A unique identifier for the specific tool instance or resource being accessed.
The await_tool_approval_response Loop
If approval is required, the daemon enters an asynchronous wait state using await_tool_approval_response crates/palyra-daemon/src/application/run_stream/tool_flow.rs#24-28. This function suspends the tool execution task and monitors for an ApprovalDecision event. The process is governed by a timeout defined by TOOL_APPROVAL_RESPONSE_TIMEOUT crates/palyra-daemon/src/application/run_stream/tool_flow.rs#28.
Data Flow: Tool Proposal to Decision
The following diagram illustrates the transition from a “Natural Language Space” request to the “Code Entity Space” of approval management. Tool Approval Sequence Sources: crates/palyra-daemon/src/application/run_stream/tool_flow.rs#53-101, crates/palyra-daemon/src/application/run_stream/tool_flow.rs#121-162Key Data Structures
ApprovalSubjectType
Categorizes the resource or action requiring approval.Tool: Standard tool execution.ChannelSend: Sending messages to external platforms.SecretAccess: Reading sensitive data from the Vault.BrowserAction: High-risk browser automation steps.NodeCapability: Execution on remote nodes.DevicePairing: Authorizing new device connections.
ApprovalDecision
Represents the final state of an approval request:Allow: Execution proceeds.Deny: Execution is blocked; adenied_execution_outcomeis returned to the model crates/palyra-daemon/src/application/run_stream/tool_flow.rs#32.Timeout: No decision was made within the allotted time.Error: System failure during the approval process.
The Approvals gRPC Service
TheApprovalsService is the primary interface for administrative tools (CLI) to interact with the approval queue. It is defined in the gateway_v1 protobuf namespace.
| Method | Role |
|---|---|
ListApprovals | Retrieves pending and historical approval records with filters for subject_type and principal. |
GetApproval | Fetches detailed context for a specific ULID-identified approval. |
ExportApprovals | Streams approval history in NDJSON or JSON format for auditing. |
DecideApproval | (Via Operator Runtime) Submits the final Allow/Deny decision. |
CLI Approval Commands
Thepalyra CLI provides the approvals command group for managing the queue from the terminal.
- List:
palyra approvals list --subject-type toolcrates/palyra-cli/src/commands/approvals.rs#35-70. - Show:
palyra approvals show <id>crates/palyra-cli/src/commands/approvals.rs#71-89. - Decide:
palyra approvals decide <id> --decision allow --scope sessioncrates/palyra-cli/src/commands/approvals.rs#136-163.
decide command supports different Approval Scopes:
Once: Applies only to the current request.Session: Authorizes the same action for the duration of the current session.Timeboxed: Authorizes the action for a specific duration (TTL).
Web Console Approvals Section
The Web Console provides a React-based interface for visual approval management. It uses theApprovalsSection component to render the review queue and detail panels.
Implementation Components:
ApprovalsSection: Main layout for the “Access” tab apps/web/src/console/sections/ApprovalsSection.tsx#30.pendingApprovals: A derived state filtering the list for items wheredecision === nullapps/web/src/console/sections/ApprovalsSection.tsx#31-33.decideApproval: Triggered by “Allow” or “Deny” buttons, communicating back to the daemon via theConsoleApiClient.
Access Control and Rate Limiting
The system enforces strict access control on who can view or decide approvals.Permissions
Approval operations require specific permissions managed by theAccessRegistry:
PERMISSION_TRUST_OPERATE: Required to decide on sensitive tool/secret approvals crates/palyra-daemon/src/access_control.rs#32.PERMISSION_OBSERVABILITY_READ: Required to list and export approval history crates/palyra-daemon/src/access_control.rs#31.
Rate Limiting
The daemon implements rate limiting for API-driven interactions. TheAppState tracks these limits in memory:
admin_rate_limit: Limits requests to administrative endpoints crates/palyra-daemon/src/app/state.rs#44.compat_api_rate_limit: Specifically limits tool-heavy completions via the OpenAI-compatible API crates/palyra-daemon/src/app/state.rs#46.