feat(linear): resolve API token via AgentCore Identity (Phase 2.0a)

[isadeks]

Summary

Phase 2.0a of the Linear v2 plan. Stacked on PR aws-samples#87 (feat/linear-processor-feedback); this PR's base is set to that branch so the diff shows only the 2.0a changes. Once aws-samples#87 merges upstream, this will rebase onto main and open against aws-samples.

Migrates the agent runtime's Linear personal API token resolution from AWS Secrets Manager to AWS Bedrock AgentCore Identity. This is the "validate the Identity SDK" step before the bigger OAuth + Gateway cutover in Phase 2.0b.

Per Alain's guidance from the v1.1 review thread:

"Ideally yeah, you can try when exposing the server through agentcore gateway. you will setup an outbound auth for your server using agentcore identity. that identity can be (AC identity is like a wrapper around secrets manager) api key or oauth. start by using api key, if it works, switch to oauth."

Scope: agent runtime only

Lambdas (orchestrator + processor) intentionally keep using Secrets Manager. Reason: the Python bedrock_agentcore SDK has no Node.js equivalent — Lambda migration requires @aws-sdk/client-bedrock-agentcore raw API calls and folds into 2.0b's bigger refactor (where OAuth tokens replace API keys for all consumers in one cutover).

End-state of 2.0a:

• Agent reads from AgentCore Identity ✓
• Lambdas read from Secrets Manager (unchanged) ✓
• Both point at the same underlying token value (admin runs agentcore add credential once and populates Linear API token in both stores)

What changed

agent/src/config.py::resolve_linear_api_token

• Drops boto3 SecretsManager fetch + LINEAR_API_TOKEN_SECRET_ARN env var
• Reads new env LINEAR_API_KEY_PROVIDER_NAME (provider name in the Identity vault, default: linear-api-key)
• Calls IdentityClient.get_api_key() with the workload access token auto-injected into BedrockAgentCoreContext by AgentCore Runtime
• Caches the resolved token in LINEAR_API_TOKEN env so downstream consumers stay unchanged: channel_mcp.py's \${LINEAR_API_TOKEN} placeholder in .mcp.json and linear_reactions.py's GraphQL Authorization header

Why imperative IdentityClient.get_api_key() instead of the @requires_api_key decorator: API keys don't need refresh. The decorator pattern shines for OAuth (refresh tokens, scopes, per-session binding) and is the right shape for 2.0b. For a static API key fetched once at agent startup, the imperative form keeps the MCP-config-with-placeholder model working unchanged.

Verified by reading the SDK's auth.py: the @requires_api_key decorator does exactly client.get_api_key(provider_name=..., agent_identity_token=BedrockAgentCoreContext.get_workload_access_token()). Inside AgentCore Runtime the context returns the auto-injected token; outside (Lambda, local dev) it returns None. Our imperative version matches that behaviour without the decorator's call-site rewrite.

Preserves PR aws-samples#87's nice-to-have improvements

• ImportError graceful fallback adapted from boto3 to bedrock_agentcore — degrade with WARN, don't crash the agent
• AccessDeniedException (likely missing IAM permission) and ResourceNotFoundException (provider name typo / not yet created) logged at ERROR severity to page someone, not WARN
• Other ClientErrors (transient throttle, network) stay at WARN

cdk/src/stacks/agent.ts

On the AgentCore runtime:

• Drops linearIntegration.apiTokenSecret.grantRead(runtime) and the LINEAR_API_TOKEN_SECRET_ARN env-var override
• Adds LINEAR_API_KEY_PROVIDER_NAME env (hardcoded 'linear-api-key' for now)
• Adds IAM for bedrock-agentcore:GetResourceApiKey + bedrock-agentcore:GetWorkloadAccessToken

Lambdas untouched. Verified at synth: only the AgentCore runtime's IAM policy and env vars changed.

Resource scope on the new IAM is * for now; the canonical AgentCore Identity ARN format isn't fully documented in public AWS docs as of 2026-05-15. Tighten in 2.0b when OAuth migration documents the resource shape.

docs/guides/LINEAR_SETUP_GUIDE.md

Adds Step 4.5 documenting the one-time admin command users run alongside the existing bgagent linear setup wizard:

agentcore add credential --type api-key --name linear-api-key
# (paste the same lin_api_… token when prompted)

Explains the dual-store setup and notes that 2.0b will retire the duplicate. Starlight mirror synced.

Tests

agent/tests/test_config.py::TestResolveLinearApiToken — 10 tests covering: cached env-var fast path; missing provider name; missing region; workload token absent (outside runtime); happy path with env-var side-effect; botocore errors swallowed; SDK returns None defensively; ImportError fallback; AccessDeniedException → ERROR severity; ResourceNotFoundException → ERROR severity.

542 agent / 1271 cdk / 196 cli — all green. Lint clean. Typecheck clean. CDK synth clean.

Phase plan context

2.0a  ← THIS PR — API key via AgentCore Identity (agent only)
2.0b  ← Linear OAuth + Gateway in one cutover (all consumers, retires Secrets Manager)
2.1   ← Agent Sessions UX (status pill, activities, retires reaction-spam)
2.2   ← AgentSessionEvent webhooks (@bgagent natural-language prompts)
2.3   ← HITL adapter via select activities (post Sam's #88 merge)

Reviewer notes

• Smoke not run yet. The MCP placeholder, GraphQL header, and run.sh env-var pass-through are all unchanged — only the source of LINEAR_API_TOKEN changed. Unit tests cover the new code path with realistic SDK mocks. Will deploy + smoke before requesting upstream review.
• Provider name hardcoded as 'linear-api-key'. Happy to parametrize via CDK context if reviewer prefers — opted for the simple shape since there's one deployment.
• Promotion to upstream: when feat(linear): v1.1 polish — pre-container feedback, state-on-start, sweep, nits aws-samples/sample-autonomous-cloud-coding-agents#87 merges, rebase this onto aws-samples/main and open the cross-fork PR against main.