feat: add prompt field for telemetry AUTO-248

[andyMrtnzP]

Summary

Adds optional prompt field for telemetry

Related issues

Closes AUTO-248

Changes

Test plan

• npm test passes locally
• npm run lint passes locally
• npm run coverage thresholds still met
• Manual smoke test against a real Browserless token (describe below)
• N/A — docs / chore / refactor only

Checklist

• I have read CONTRIBUTING.md
• My commits follow the conventional-commit prefix convention
• I have updated documentation where relevant (README, CHANGELOG, etc.)
• I have not introduced new dependencies without flagging them in the summary

Summary by CodeRabbit

• New Features
  • Added optional prompt context to supported tool requests.
  • Added best-effort redaction for sensitive content included in prompt-related analytics.
  • Compliance mode continues to exclude prompt fields from tool schemas.
• Analytics
  • Tool activity analytics can now record originating prompt context when present.
• Tests
  • Added coverage for prompt capture, secret redaction, and compliance mode behavior.
• Documentation
  • Updated inline documentation for frontmatter parsing behavior (no runtime changes).

[coderabbitai]

Walkthrough

defineTool now conditionally accepts an LLM-injected _prompt, redacts secrets, passes it through ToolRunContext, and records it in analytics. Agent and crawl tools propagate the prompt, with tests covering redaction and compliance-mode behavior.

Changes

Prompt Context Propagation

Layer / File(s)	Summary
defineTool prompt contract and execution handling src/lib/define-tool.ts, src/lib/utils.ts	Adds conditional _prompt schema support, secret redaction, context propagation, and prompt-aware analytics fields.
Downstream tool analytics propagation src/tools/agent.ts, src/tools/crawl.ts, test/tools/agent.spec.ts	Propagates prompt context through agent and crawl analytics and tests redaction and compliance-mode suppression.
Frontmatter parser documentation src/skills/sites.ts	Updates comments to describe the existing minimal frontmatter reader and folded scalar handling.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant LLM
  participant defineTool
  participant Tool
  participant Analytics
  LLM->>defineTool: Invoke with _prompt
  defineTool->>Tool: Pass params and redacted prompt
  Tool->>Analytics: Emit prompt-aware analytics

Loading

Possibly related PRs

• browserless/browserless-mcp#130: Modifies the same defineTool execution-context plumbing.
• browserless/browserless-mcp#147: Updates the browserless_agent analytics payload with additional context.
• browserless/browserless-mcp#166: Modifies compliance-mode behavior for the same tool surface.

Poem

A bunny found a prompt in flight,
Scrubbed its secrets clean and bright.
Tools carried context through the run,
Analytics noted what was done.
Compliance kept the field away—
Hop, hop, safer logs today!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly matches the main change: adding an optional prompt field for telemetry.
Description check	✅ Passed	The description covers the summary, related issue, test plan, and checklist, and is mostly complete for the template.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/record-prompt-auto-248

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/tools/agent.ts`:
- Around line 516-524: Remove the raw console.log(prompt) call from the agent
handler. If prompt diagnostics are required, route them through the existing log
helper with its redaction behavior, preserving the surrounding handler logic and
parameters.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: baf8615b-b120-4a2a-b9b4-65fef17666e1

📥 Commits

Reviewing files that changed from the base of the PR and between 3b89b8a and e60377e.

📒 Files selected for processing (4)

• src/lib/define-tool.ts
• src/tools/agent.ts
• src/tools/crawl.ts
• test/lib/define-tool.spec.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/lib/utils.ts`:
- Line 85: Update the credential-redaction pattern in the utility to match
JSON-style fields with quoted keys and quoted or unquoted values, while
preserving existing unquoted formats. Add a regression case covering a payload
such as a password field containing a secret and verify the value is redacted
before analytics forwarding.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 99e56381-7112-4ff4-b62f-38a82337f7c9

📥 Commits

Reviewing files that changed from the base of the PR and between e60377e and 948eb91.

📒 Files selected for processing (4)

• src/lib/define-tool.ts
• src/lib/utils.ts
• src/tools/agent.ts
• test/tools/agent.spec.ts

💤 Files with no reviewable changes (1)

• src/tools/agent.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/define-tool.ts