feat(invoke): add --prompt-file and stdin support for long prompts

[aidandaly24]

Description

Adds two new prompt sources to agentcore invoke to work around shell argument length limits (E2BIG, typically 128KB–2MB on macOS/Linux) that block long prompts today:

• --prompt-file <path> — read the prompt from a file
• piped stdin — when no prompt is given and stdin is not a TTY, read from stdin

This unblocks common AI-agent workflows: passing multi-turn JSON conversations, structured payloads, and chaining agentcore invoke calls via pipes (jq ... | agentcore invoke, agent-to-agent chaining, etc.).

Precedence

Hybrid — backward-compatible with today's --prompt/positional precedence:

--prompt  >  positional  >  --prompt-file  >  stdin

--prompt-file combined with piped stdin content returns an explicit collision error rather than silently picking one, since both are "bulk" sources and silent precedence there would mask user mistakes (e.g. a CI pipeline accidentally piping data while also passing --prompt-file).

Examples

# Works (new)
agentcore invoke --prompt-file prompt.json --json
cat long-prompt.txt | agentcore invoke --json
jq -r '.response' result.json | agentcore invoke --json

# Still works (unchanged)
agentcore invoke "hello world"
agentcore invoke --prompt "hello world"

# Errors cleanly
echo foo | agentcore invoke --prompt-file prompt.txt
# → {"success":false,"error":"Cannot combine --prompt-file with piped stdin. Provide only one prompt source."}

Related Issue

Closes #686

Documentation PR

N/A — this change adds a self-documenting CLI flag (shows in --help). Happy to open a docs PR if the team wants the pipeline/file-input pattern called out in the guide.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Testing detail

1. Unit tests — new resolve-prompt.test.ts (11/11 passing) covering every precedence branch, file read, stdin read, collision error, missing file, trailing-newline trim, and empty-string handling.

2. CLI surface — --prompt-file appears in agentcore invoke --help:

3. End-to-end against a live deployed runtime. I deployed a deterministic echo agent (returns PROMPT_LEN + SHA256 of the received prompt) to AgentCore Runtime in us-east-1 and verified byte-exact prompt delivery for each source. Local and agent-returned SHA256 match for all three prompt paths including a 5000-byte random payload:

4. Error paths fire correctly against the live runtime (collision returns immediately — no cold-start penalty):

Test matrix

Source	Local SHA256	Agent-returned SHA256	Len	Match
--prompt-file (5KB random)	55d75163…e6	55d75163…e6	5000	✅
stdin pipe (5KB random)	55d75163…e6	55d75163…e6	5000	✅
positional "quick hello"	74336f76…a0	74336f76…a0	11	✅
positional "hi"	8f434346…a4	8f434346…a4	2	✅
--prompt-file + piped stdin	—	{"success":false,"error":"Cannot combine…"}	—	✅
--prompt-file missing path	—	{"success":false,"error":"Failed to read --prompt-file '…': ENOENT…"}	—	✅

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

Implementation notes for reviewers

• New file src/cli/commands/invoke/resolve-prompt.ts owns source resolution. action.ts is unchanged — it still consumes a plain options.prompt: string, so all downstream protocols (non-stream, stream, A2A, AGUI, MCP, --exec) inherit the new behavior automatically.
• src/test-utils/cli-runner.ts now spawns with stdio: ['ignore', ...] so the new !process.stdin.isTTY detection doesn't false-trigger when tests drive the CLI without piping stdin.
• process.stdin.isTTY === false is the standard non-interactive-stdin signal; we additionally treat empty stdin (immediate EOF) as "no stdin source" so scripts without piped input fall through to the existing "No prompt provided" error.
• Collision check runs after stdin drain so the check only fires when stdin actually has content — a piped-but-empty stdin (e.g. from a test harness) doesn't collide with --prompt-file.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[Hweinstock]

LGTM!