Feat/tool execution approval #147

rossmanko · 2025-12-26T16:48:36Z

Summary by CodeRabbit

Release Notes

New Features
- Introduced tool approval workflow for terminal commands with three execution modes: ask every time, auto-run sandbox, or run everything.
- New command approval interface includes copy, run, and skip actions with keyboard shortcut support (Enter to approve).
- Messages now automatically continue after tool approval responses.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

vercel · 2025-12-26T16:48:41Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
hackerai	Ready	Preview, Comment	Dec 26, 2025 4:50pm

coderabbitai · 2025-12-26T16:48:47Z

📝 Walkthrough

Walkthrough

These changes implement a tool approval workflow with configurable auto-run modes. A new AutoRunMode type is introduced with three options: "ask-every-time", "auto-run-sandbox", and "run-everything". The system propagates this mode through global state, tool contexts, and message handling pipelines. A new approval detection utility identifies approval-related message continuations. The chat handler and terminal tool components now support approval workflows, conditionally saving messages and routing to a new UI component for command approval/execution.

Changes

Cohort / File(s)	Summary
Type & State Setup `types/agent.ts`, `app/contexts/GlobalState.tsx`	Added `AutoRunMode` type with three literal options. Extended `GlobalStateType` with `autoRunMode` state and `setAutoRunMode` setter; persists to localStorage. Extended `ToolContext` interface with optional `autoRunMode` and `sandboxPreference` fields.
Tool Factory & Context `lib/ai/tools/index.ts`	Updated `createTools` signature to accept optional `autoRunMode` parameter; propagates it through `ToolContext` object.
Terminal Tool Execution `lib/ai/tools/run-terminal-cmd.ts`	Destructures `autoRunMode` and `sandboxPreference` from context; computes `needsApproval` logic based on mode and sandbox preference; conditionally includes `needsApproval` in tool input schema when required.
Approval Utility `lib/utils/approval-detection.ts`	New utility file exporting `isApprovalContinuation()` function to detect approval-state messages in chat history.
Message UI Rendering `app/components/Messages.tsx`, `app/components/MessagePartHandler.tsx`	Both components now accept and propagate new optional `addToolApprovalResponse` prop (from `@ai-sdk/react`) to child handlers, enabling tool approval callbacks in the message rendering pipeline.
Chat Component & Logic `app/components/chat.tsx`	Integrated approval detection for continuation logic; auto-continue after approved actions; threads `addToolApprovalResponse` and `autoRunMode` through message rendering; includes `autoRunMode` in outgoing chat request body.
Terminal Approval UI `app/components/tools/TerminalCommandApproval.tsx`	New component handling three approval states: "approval-requested" (renders command preview, mode selector, keyboard shortcuts), "approval-responded" (renders status block), and "output-denied" (renders rejection block). Integrates clipboard copy, approval/rejection actions, and keyboard hotkey support.
Terminal Tool Handler `app/components/tools/TerminalToolHandler.tsx`	Extended to route approval-related states (`approval-requested`, `approval-responded`, `output-denied`) to new `TerminalCommandApproval` component. Accepts `addToolApprovalResponse` prop and reads `autoRunMode`/`setAutoRunMode` from global state; passes both through to approval UI.
Agent Configuration UI `app/components/AgentsTab.tsx`	Added new "Tool Approval" section under Pro/Ultra/Team offering a Select control bound to `autoRunMode` with three options and descriptive labels.
Approval-Aware Chat Handling `lib/api/chat-handler.ts`	Uses `isApprovalContinuation()` to detect approval flows; conditionally skips user message saving and uses mock rate-limit for approval continuations; reuses `assistantMessageId` for continuation requests; refactors stream orchestration to expose `getTodoManager`, `getFileAccumulator`, and `titlePromise` at higher scope for `onFinish` access; includes conditional persistence logic.
Message Merge Logic `lib/db/actions.ts`	In `getMessagesByChatId`, added detection for approval-related messages (`approval-responded` or `output-denied` states); replaces matching existing message instead of appending when approval message detected.
Message Persistence `convex/messages.ts`	Extended `saveMessage` to update existing messages by conditionally building `updateFields` (parts, content, file_ids, update_time); patches only if non-update_time fields are present; adds per-file error handling when marking attachments.
Formatting & Type Annotation `app/components/SharedLinksTab.tsx`, `app/hooks/useFileUrlCache.ts`	Minor formatting adjustments with no functional changes.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Chat UI
    participant Chat Handler
    participant Tool Context
    participant Terminal Tool
    participant Tool Approval UI

    User->>Chat UI: Send message with terminal command
    Chat UI->>Chat Handler: Route request with autoRunMode
    Chat Handler->>Tool Context: Provide autoRunMode + sandboxPreference
    Tool Context->>Terminal Tool: Create tool with context
    Terminal Tool->>Terminal Tool: Compute needsApproval flag
    
    alt needsApproval = true
        Terminal Tool->>Chat Handler: Include needsApproval in response
        Chat Handler->>Chat UI: Stream approval-requested state
        Chat UI->>Tool Approval UI: Render command preview + mode selector
        
        User->>Tool Approval UI: Enter/Click "Run" to approve
        Tool Approval UI->>Chat UI: Call addToolApprovalResponse (approved)
        Chat UI->>Chat Handler: Detect approval continuation
        Chat Handler->>Chat Handler: Auto-continue with approved state
        Chat Handler->>Terminal Tool: Re-execute command
        Terminal Tool->>Chat Handler: Return command output
        Chat Handler->>Chat UI: Stream approval-responded + output
        Chat UI->>Tool Approval UI: Render execution status/result
    else needsApproval = false
        Terminal Tool->>Chat Handler: Execute immediately (no approval)
        Chat Handler->>Chat UI: Stream result directly
    end
    
    Chat UI->>User: Display final result

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

Feat/local terminal execution #7: Modifies lib/ai/tools/run-terminal-cmd.ts with different execution mode handling; overlaps on tool context enrichment and command execution paths.
feat: Add sidebar navigation controls and auto-follow functionality #113: Updates TerminalToolHandler.tsx for sidebar streaming and output rendering; shares the same component used for approval routing in this PR.
Daily branch 2025 09 28 #40: Extends createTools signature and ToolContext shape in lib/ai/tools/index.ts with file accumulator fields; parallel changes to the same tool factory.

Poem

🐰 A rabbit hops through approval gates,
With auto-modes that escalate—
Commands now ask before they run,
Or sandbox first, then all-or-none,
The chat flows on, the tooling's blessed! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Feat/tool execution approval' directly and clearly describes the main feature being added—a tool execution approval workflow.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/tool-execution-approval

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🧹 Nitpick comments (5)

types/agent.ts (1)
46-47: Use the AutoRunMode type instead of duplicating the literal union.

Line 46 duplicates the string literals instead of referencing the AutoRunMode type defined on lines 30-33. This creates a maintenance risk if the type is updated.
Proposed fix
-  autoRunMode?: "ask-every-time" | "auto-run-sandbox" | "run-everything";
+  autoRunMode?: AutoRunMode;
lib/db/actions.ts (1)

337-360: Consider reusing isApprovalContinuation from lib/utils/approval-detection.ts.

The approval detection logic here (lines 339-349) duplicates similar checks from the new approval-detection.ts utility. Consider extracting a shared helper to avoid drift between the two implementations.

Also note: if approvalMessage.id doesn't match any existing message, the .map() on line 353 silently returns existingMessages unchanged. Verify this is the intended behavior for new approval messages.

app/components/AgentsTab.tsx (1)

251-258: Consider adding a confirmation dialog for "Run Everything" mode.

The "Run Everything (Unsandboxed)" option bypasses all safety checks. Consider adding a confirmation dialog when selecting this option, similar to other dangerous operations in the app (e.g., unshare confirmations). This would prevent accidental selection of the most permissive mode.
app/contexts/GlobalState.tsx (1)
257-264: Consider validating localStorage value.

The localStorage value is cast directly to AutoRunMode without validation. If localStorage contains an invalid value (e.g., from a previous version or tampering), it could cause unexpected behavior.
🔎 Suggested validation
  const [autoRunMode, setAutoRunMode] = useState<AutoRunMode>(() => {
    if (typeof window === "undefined") return "auto-run-sandbox";
-   return (
-     (localStorage.getItem("auto-run-mode") as AutoRunMode) ||
-     "auto-run-sandbox"
-   );
+   const stored = localStorage.getItem("auto-run-mode");
+   const validModes = ["ask-every-time", "auto-run-sandbox", "run-everything"];
+   return validModes.includes(stored || "") 
+     ? (stored as AutoRunMode) 
+     : "auto-run-sandbox";
  });
lib/api/chat-handler.ts (1)
248-249: Validate autoRunMode before casting.

The autoRunMode comes from the client request body as a string and is cast directly to AutoRunMode. A malicious or buggy client could send an invalid value.
🔎 Suggested validation
+ const validAutoRunModes = ["ask-every-time", "auto-run-sandbox", "run-everything"];
+ const validatedAutoRunMode = validAutoRunModes.includes(autoRunMode || "")
+   ? (autoRunMode as AutoRunMode)
+   : undefined;

  const {
    tools,
    // ...
  } = createTools(
    // ...
-   autoRunMode as AutoRunMode | undefined,
+   validatedAutoRunMode,
  );

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 65cc5af and 1c68aed.

⛔ Files ignored due to path filters (1)

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (16)

app/components/AgentsTab.tsx
app/components/MessagePartHandler.tsx
app/components/Messages.tsx
app/components/SharedLinksTab.tsx
app/components/chat.tsx
app/components/tools/TerminalCommandApproval.tsx
app/components/tools/TerminalToolHandler.tsx
app/contexts/GlobalState.tsx
app/hooks/useFileUrlCache.ts
convex/messages.ts
lib/ai/tools/index.ts
lib/ai/tools/run-terminal-cmd.ts
lib/api/chat-handler.ts
lib/db/actions.ts
lib/utils/approval-detection.ts
types/agent.ts

🧰 Additional context used

📓 Path-based instructions (1)

convex/**/*.{ts,js}

📄 CodeRabbit inference engine (.cursor/rules/convex_rules.mdc)

convex/**/*.{ts,js}: ALWAYS use the new function syntax for Convex functions with query, mutation, action decorators that include args, returns, and handler properties
Use array validators with v.array() to validate array arguments and schema fields
Use discriminated union types with v.union() and v.literal() for schema validation
Always use the v.null() validator when a function returns a null value
Use v.id(tableName) validator for document ID validation and Id<'tableName'> TypeScript type for ID fields
v.bigint() is deprecated; use v.int64() instead for representing signed 64-bit integers
Use v.record() for defining record types; v.map() and v.set() are not supported
Index fields must be queried in the same order they are defined; create separate indexes if you need different query orders
Use internalQuery, internalMutation, and internalAction for private functions that should not be part of the public API
Use query, mutation, and action for public functions that are exposed to the public API
ALWAYS include argument and return validators for all Convex functions including query, internalQuery, mutation, internalMutation, action, and internalAction
Functions that don't return anything should include returns: v.null() as the output validator
Functions implicitly return null in JavaScript if they have no return statement
Use ctx.runQuery to call a query from a query, mutation, or action
Use ctx.runMutation to call a mutation from a mutation or action
Use ctx.runAction to call an action from an action
Only call an action from another action if you need to cross runtimes (e.g., V8 to Node); otherwise extract shared code into a helper async function
Use as few calls from actions to queries and mutations as possible to avoid race conditions from split transaction logic
Pass a FunctionReference to ctx.runQuery, ctx.runMutation, or ctx.runAction; do not pass the callee function directly
When usi...

Files:

convex/messages.ts

🧠 Learnings (11)

📚 Learning: 2025-11-28T01:16:26.536Z

Learnt from: fkesheh
Repo: hackerai-tech/hackerai PR: 114
File: lib/ai/tools/utils/convex-sandbox.ts:95-145
Timestamp: 2025-11-28T01:16:26.536Z
Learning: In the local sandbox architecture (lib/ai/tools/utils/convex-sandbox.ts), background command execution semantics are handled by the local sandbox client (packages/local/src/index.ts), not by the ConvexSandbox class. When background: true, the local client immediately submits a result with empty output and PID after spawning the process, causing waitForResult() to resolve immediately and maintaining E2B-compatible non-blocking behavior.

Applied to files:

types/agent.ts
lib/ai/tools/run-terminal-cmd.ts
lib/api/chat-handler.ts