Additional agent logging

[miguelg719]

why

To inform the user throughout the agent execution process

what changed

Added logs to tool calls, and on the stagehand agent handler

test plan

• tested locally

[changeset-bot]

🦋 Changeset detected

Latest commit: 82c04de

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Greptile Overview

Summary

This PR adds comprehensive logging throughout the agent execution process to improve observability and user feedback. The changes implement a consistent logging pattern across all agent tools (act, extract, goto, scroll, navback, fillform, ariaTree, close) and enhance logging in the main agent handler. Each tool now logs when it's called with structured data including the tool name, parameters, and argument types. The PR also includes a breaking change in the close tool, renaming the `taskComplete` parameter to `success` for better clarity and consistency.

The logging follows a standardized pattern using the existing stagehand logger with category "agent", level 1, and structured auxiliary data. In the main agent handler (stagehandAgentHandler.ts), the PR adds detailed logging for task initialization, configuration details, agent reasoning steps, and completion status. One log was removed from the observe handler to reduce verbosity.

These changes integrate well with the existing logging infrastructure, building upon the structured JSON logging system that was introduced in earlier versions (as seen in the changelog). The consistent logging pattern across tools ensures uniform observability throughout agent workflows.

Important Files Changed

Changed Files

Filename	Score	Overview
lib/agent/tools/act.ts	5/5	Added structured logging for tool calls and updated action descriptions
lib/agent/tools/ariaTree.ts	5/5	Added consistent logging when agent calls the ariaTree tool
lib/agent/tools/close.ts	4/5	Renamed parameter from taskComplete to success for consistency
lib/agent/tools/extract.ts	5/5	Added logging with instruction and schema parameters for tool calls
lib/agent/tools/fillform.ts	5/5	Added logging to track form filling operations with field data
lib/agent/tools/goto.ts	5/5	Added structured logging for navigation tool calls with URL parameter
lib/agent/tools/navback.ts	5/5	Added consistent logging pattern for navigation back operations
lib/agent/tools/scroll.ts	5/5	Added logging with scroll parameters (pixels and direction)
lib/handlers/observeHandler.ts	4/5	Removed 'starting observation' log message to reduce verbosity
lib/handlers/stagehandAgentHandler.ts	4/5	Added comprehensive agent execution logging and updated close tool handling

Confidence score: 4/5

• This PR is safe to merge with good implementation of logging improvements across agent tools
• Score reflects well-structured logging additions but includes a breaking change in the close tool parameter rename
• Pay close attention to lib/agent/tools/close.ts and lib/handlers/stagehandAgentHandler.ts for the parameter rename impact

Sequence Diagram

sequenceDiagram
    participant User
    participant StagehandAgentHandler
    participant Logger
    participant Tools
    participant LLMClient
    participant Stagehand

    User->>StagehandAgentHandler: "execute(instruction)"
    StagehandAgentHandler->>Logger: "log agent task execution"
    StagehandAgentHandler->>StagehandAgentHandler: "buildSystemPrompt(instruction)"
    StagehandAgentHandler->>StagehandAgentHandler: "createTools()"
    StagehandAgentHandler->>LLMClient: "generateText() with tools"
    
    loop For each tool call
        LLMClient->>Tools: "call tool (act/extract/goto/screenshot/etc.)"
        Tools->>Logger: "log tool call"
        alt Tool is act
            Tools->>Stagehand: "page.observe()"
            Stagehand-->>Tools: "observe results"
            Tools->>Stagehand: "page.act()"
            Stagehand-->>Tools: "action result"
        else Tool is extract
            Tools->>Stagehand: "page.extract()"
            Stagehand-->>Tools: "extracted data"
        else Tool is goto
            Tools->>Stagehand: "page.goto(url)"
            Stagehand-->>Tools: "navigation result"
        else Tool is screenshot
            Tools->>Stagehand: "page.screenshot()"
            Stagehand-->>Tools: "screenshot buffer"
        else Tool is ariaTree
            Tools->>Stagehand: "page.extract() for accessibility"
            Stagehand-->>Tools: "accessibility tree"
        else Tool is scroll
            Tools->>Stagehand: "page.mouse.wheel()"
            Stagehand-->>Tools: "scroll result"
        else Tool is navback
            Tools->>Stagehand: "page.goBack()"
            Stagehand-->>Tools: "navigation result"
        else Tool is fillform
            Tools->>Stagehand: "page.observe() then page.act() multiple times"
            Stagehand-->>Tools: "form fill results"
        else Tool is close
            Tools->>Tools: "return completion status"
        end
        Tools-->>LLMClient: "tool result"
        LLMClient->>StagehandAgentHandler: "onStepFinish callback"
        StagehandAgentHandler->>Logger: "log agent reasoning"
    end
    
    LLMClient-->>StagehandAgentHandler: "final result with usage"
    StagehandAgentHandler->>Logger: "log task completion"
    StagehandAgentHandler-->>User: "AgentResult with actions and success status"

Loading

_{10 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

logic: Logic issue: the success check only sets finalMessage when success is true, but doesn't handle the false case. This could leave finalMessage empty for failed tasks.

Suggested change

	const { success, reasoning } = args;
	if (success) {
	const closeReasoning = reasoning as string;
	const allReasoning = collectedReasoning.join(" ");
	finalMessage = closeReasoning
	? `${allReasoning} ${closeReasoning}`.trim()
	: allReasoning || "Task completed successfully";
	: allReasoning || `Task completed with success: ${success}`;
	}
	const { success, reasoning } = args;
	const closeReasoning = reasoning as string;
	const allReasoning = collectedReasoning.join(" ");
	if (success) {
	finalMessage = closeReasoning
	? `${allReasoning} ${closeReasoning}`.trim()
	: allReasoning || "Task completed successfully";
	} else {
	finalMessage = closeReasoning
	? `${allReasoning} ${closeReasoning}`.trim()
	: allReasoning || "Task failed to complete";
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: lib/handlers/stagehandAgentHandler.ts
Line: 159:166

Comment:
logic: Logic issue: the success check only sets finalMessage when success is true, but doesn't handle the false case. This could leave finalMessage empty for failed tasks.

```suggestion
                const { success, reasoning } = args;
                const closeReasoning = reasoning as string;
                const allReasoning = collectedReasoning.join(" ");
                if (success) {
                  finalMessage = closeReasoning
                    ? `${allReasoning} ${closeReasoning}`.trim()
                    : allReasoning || "Task completed successfully";
                } else {
                  finalMessage = closeReasoning
                    ? `${allReasoning} ${closeReasoning}`.trim()
                    : allReasoning || "Task failed to complete";
                }
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

style: The fallback message includes the success boolean value in the string, which may not provide meaningful information to users (e.g., 'Task completed with success: true').

Prompt To Fix With AI

This is a comment left during a code review.
Path: lib/handlers/stagehandAgentHandler.ts
Line: 165:165

Comment:
style: The fallback message includes the success boolean value in the string, which may not provide meaningful information to users (e.g., 'Task completed with success: true').

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

syntax: Schema value is incorrectly typed as 'object' when it's actually a string parameter. Should be 'string' to match the parameter type.

Suggested change

	// TODO: check if we want to log this
	schema: {
	value: schema,
	type: "object",
	},
	},
	// TODO: check if we want to log this
	schema: {
	value: schema,
	type: "string",
	},

Prompt To Fix With AI

This is a comment left during a code review.
Path: lib/agent/tools/extract.ts
Line: 82:87

Comment:
syntax: Schema value is incorrectly typed as 'object' when it's actually a string parameter. Should be 'string' to match the parameter type.

```suggestion
            // TODO: check if we want to log this
            schema: {
              value: schema,
              type: "string",
            },
```

How can I resolve this? If you propose a fix, please make it concise.