feat: add agent header support

[JackZhao10086]

Summary

Add support for the AGENT_TRACE environment variable: when set, its value is automatically injected as the X-Agent-Trace header on every outgoing HTTP request (both direct and SDK paths).

Changes

• Add CliAgentTrace = "AGENT_TRACE" to internal/envvars/envvars.go
• Add HeaderAgentTrace = "X-Agent-Trace" constant to internal/cmdutil/secheader.go
• Add AgentTraceValue() function that reads the AGENT_TRACE env var
• Modify BaseSecurityHeaders() to conditionally include X-Agent-Trace when the env var is non-empty
• Add unit tests covering both env-set and env-unset scenarios

Test Plan

• Unit tests pass (TestAgentTraceValue_EmptyWhenEnvUnset, TestAgentTraceValue_ReturnsEnvValue, TestBaseSecurityHeaders_NoAgentTraceHeaderWhenEnvUnset, TestBaseSecurityHeaders_IncludesAgentTraceHeaderWhenEnvSet)
• Manual local verification confirms the lark-cli <domain> <command> flow works as expected

Related Issues

• None

Summary by CodeRabbit

• New Features
  • Optional agent-trace header can be added to outbound requests by setting a new environment variable; values are trimmed and validated.
  • Unsafe or empty values (including newline/control characters or overly long values) are ignored to prevent header injection.
• Tests
  • Added tests covering sanitization, length enforcement, and conditional inclusion of the header.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f1dfb624-7427-4ed3-9d9f-16d10d217943

📥 Commits

Reviewing files that changed from the base of the PR and between a05000a and d79bf75.

📒 Files selected for processing (3)

• internal/cmdutil/secheader.go
• internal/cmdutil/secheader_test.go
• internal/envvars/envvars.go

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

• internal/cmdutil/secheader_test.go

---

📝 Walkthrough

Walkthrough

Adds CliAgentTrace env constant (LARKSUITE_CLI_AGENT_TRACE), a HeaderAgentTrace constant and AgentTraceValue() reader that trims and rejects control characters/overlength values, and updates BaseSecurityHeaders() to include X-Agent-Trace only when validated. Tests exercise trimming, control-char rejection, and length rules.

Changes

Agent trace header propagation

Layer / File(s)	Summary
Environment variable definition internal/envvars/envvars.go	New exported constant CliAgentTrace defines LARKSUITE_CLI_AGENT_TRACE for agent trace propagation.
Header constant and value reader internal/cmdutil/secheader.go	Adds imports (os, internal/envvars, unicode); defines HeaderAgentTrace ("X-Agent-Trace"); implements AgentTraceValue() that trims, enforces max length, and rejects Unicode control characters; updates BaseSecurityHeaders() to conditionally include the header when the value is valid.
Test coverage for agent trace header internal/cmdutil/secheader_test.go	Adds internal/envvars import and tests verifying AgentTraceValue() and BaseSecurityHeaders() behavior for unset, trimmed, whitespace-only, control-character-containing, and over-length env values.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A tiny trace that skips and hops,
From env to header, then it stops.
Trimmed and clean, no hidden line,
X-Agent-Trace now toes the line.
A quiet hop — the header's fine.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 19.05% 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
Title check	✅ Passed	The title 'feat: add agent header support' clearly summarizes the main change: adding support for the agent trace header feature.
Description check	✅ Passed	The pull request description is comprehensive and follows the template structure with all required sections (Summary, Changes, Test Plan, Related Issues) properly filled out.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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/agent_header

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@d79bf753b72ef580afe5988d214467b8373fefc6

🧩 Skill update

npx skills add larksuite/cli#feat/agent_header -y -g

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.78%. Comparing base (8d496b8) to head (d79bf75).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1158      +/-   ##
==========================================
+ Coverage   68.71%   68.78%   +0.07%     
==========================================
  Files         627      628       +1     
  Lines       58451    58680     +229     
==========================================
+ Hits        40163    40363     +200     
- Misses      14999    15021      +22     
- Partials     3289     3296       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[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 `@internal/cmdutil/secheader.go`:
- Around line 62-64: Reject/control-sanitize AGENT_TRACE before setting
X-Agent-Trace: read the value from AgentTraceValue(), trim surrounding
whitespace, and only call h.Set(HeaderAgentTrace, v) if the trimmed value is
non-empty and contains no CR or LF (e.g., check strings.ContainsAny(v, "\r\n")
or use unicode.IsControl) to prevent injection/malformed headers; reference
AgentTraceValue(), HeaderAgentTrace and the h.Set call when making the change.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5896bb05-fb3a-4161-a953-408f46cf41e3

📥 Commits

Reviewing files that changed from the base of the PR and between 893555a and cba81db.

📒 Files selected for processing (3)

• internal/cmdutil/secheader.go
• internal/cmdutil/secheader_test.go
• internal/envvars/envvars.go

[coderabbitai]

Actionable comments posted: 0