feat(agy): offload large prompts to temp file for agy CLI by mvance · Pull Request #389 · steipete/summarize

mvance · 2026-08-16T17:50:41Z

Rationale

Using --cli agy (Antigravity CLI wrapper) triggers an explicit prompt length failure when summarizing large web pages, transcripts, or stdin input because prompts were formatted directly as command-line argv flag arguments (agy --print "<prompt>"), hitting OS ARG_MAX buffer limits (~120 KB on macOS/Linux or Windows command limits).

Proposed Solution

Offload prompts exceeding platform argv limits to a secure temporary file and pass a file:// URI reference in --print, mirroring the pattern used by the pi CLI provider (src/llm/cli-runners/pi.ts):

Temp File Offloading (src/llm/cli-runners/plain.ts): When promptSize > limit (or Windows command length limit), creates a temporary directory (summarize-agy-prompt-) inside isolatedCwd (if --sandbox is enabled) or system tmpdir().
Security & Cleanup: Writes the file with restricted { mode: 0o600 } permissions and guarantees recursive deletion of prompt directories in finally blocks on success, error, or process timeout.
Documentation (docs/cli.md): Updated docs/cli.md to document automatic temp file offloading for large agy prompts.

Live Behavior Proof (Real Execution)

Below is the verified terminal execution log running summarize --cli agy against a 342 KB (342,001 character) input file using agy 1.1.13:

Environment & Input

agy version: 1.1.13
Input File: /tmp/large-test-input.txt (342,001 characters / 334 KB text payload)
Command: summarize --cli agy --plain /tmp/large-test-input.txt

Terminal Output

$ ls -lh /tmp/large-test-input.txt
-rw-r--r--@ 1 mvance  wheel   334K Aug 16 13:04 /tmp/large-test-input.txt

$ summarize --cli agy --plain /tmp/large-test-input.txt
The file prompt.txt (file:///var/folders/sy/b7g914bs2vj_jfwpzlldltjh0000gn/T/summarize-agy-mdLZlK/summarize-agy-prompt-SOmUqs/prompt.txt) is a structured prompt template designed for an LLM summarization task...

### Summary of File Contents

#### 1. Instructions (<instructions>)
Defines strict guidelines and formatting rules for summarizing input documents...

#### 2. Context Metadata (<context>)
- Filename: large-test-input.txt
- Media Type: text/plain
- Content Length: 342,001 characters.

#### 3. Payload Content (<content>)
- Consists of repeated text payload spanning ~342 KB.

via model cli/agy
8.8s · cli/agy

Tests & Quality Gate

Added unit tests in tests/llm.cli.agy.test.ts covering temp file offloading, 0o600 permissions, error cleanup, and sandbox interaction.
Verified that pnpm -s check passes all 3,000+ test suites and meets strict 85% coverage requirements across Statements, Branches, Functions, and Lines.

…tion

…ding

clawsweeper · 2026-08-16T17:50:45Z

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

clawsweeper · 2026-08-16T17:53:53Z

Codex review: needs maintainer review before merge. Reviewed August 22, 2026, 6:56 AM ET / 10:56 UTC.

ClawSweeper review

What this changes

The PR stores oversized agy prompts in a private temporary file, asks agy to read it through a file URL, then removes the file after the CLI exits.

Merge readiness

⚠️ Ready for maintainer review - 3 items remain

Keep this PR open for a maintainer compatibility decision: it replaces current main’s explicit large-prompt rejection with behavior that relies on agy following a natural-language file URL reference, demonstrated only on agy 1.1.13.

Priority: P2
Reviewed head: 7babc54478275e4fb0ff92f195d2f104eab7b1d6
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The patch is focused, tested, and backed by a real large-input run, with the remaining concern being the accepted agy compatibility boundary.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (terminal): The PR body provides after-fix terminal output for a 342 KB input using agy 1.1.13, showing the file-reference path produced a response.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): The PR body provides after-fix terminal output for a 342 KB input using agy 1.1.13, showing the file-reference path produced a response.
Evidence reviewed	5 items	Current-main behavior: Current main intentionally rejects agy prompts above the platform argv limit rather than attempting a file-based input path. Proposed implementation: The PR creates a 0600 prompt file, passes a file URL in the print instruction, checks final command size, and removes temporary directories in finally. Provider-contract dependency: The new behavior depends on agy treating the PR-generated natural-language file URL instruction as readable content; the supplied proof establishes this for agy 1.1.13 only.
Findings	None	None.
Security	None	None.

Live Verification

Command: pnpm -s dev:cli --help

Result: PASS (completed)

pnpm -s dev:cli --help
runner@runnervm76f27:/tmp/clawsweeper-live-proof-389-pFas6v/target$ pnpm -s dev:cli --help
$ node --import ./scripts/register-typescript.mjs src/cli.ts --help
pnpm -s dev:cli --help
Usage: summarize [options] [input]

Summarize web pages and YouTube links (uses direct provider API keys).

Arguments:
  input                             URL, local file path, or - for stdin (text or binary) to summarize

Options:
  --youtube ‹mode›                  YouTube transcript source: auto, web, no-auto (skip auto-generated captions), yt-dlp, apify (default: "auto")
  --transcriber ‹name›              Local transcription stage: auto (default), whisper, parakeet, canary; Groq still runs first when keyed (choices: "auto",
                                    "whisper", "parakeet", "canary")
  --diarize [provider]              Add speaker labels to YouTube or direct audio/video: auto (ElevenLabs then OpenAI), elevenlabs, openai. (choices: "auto",
                                    "elevenlabs", "openai", preset: "auto")
  --identify-speakers               Resolve diarization labels to real names using timestamp anchors and OpenAI context.
  --no-identify-speakers            Keep generic diarization labels even when speaker identification is configured.
  --speaker-profile ‹name›          Speaker profile from ~/.summarize/config.json (implies --identify-speakers).
  --speaker-at ‹timestamp=name›     Identify the speaker active at a timestamp; repeat for multiple speakers. (default: [])
  --remember-speakers               Persist resolved mappings and anchors under the selected speaker profile. (default: false)
  --video-mode ‹mode›               Video handling: auto (prefer video understanding if supported), transcript, understand. (choices: "auto", "transcript",
                                    "understand", default: "auto")
  --embedded-video ‹mode›           Embedded YouTube handling: auto, off, prefer transcript, or combine article+transcript. (choices: "auto", "off", "prefer",
                                    "both", default: "auto")
  --slides [value]                  Extract slides for YouTube/direct video URLs or local video files and render them inline inside the summary narrative (when
                                    supported). Combine with --extract to interleave slides in the full transcript.
  --no-slides                       Disable configured slide extraction for this run.
  --slides-debug                    Show slide image paths instead of rendering inline images. (default: false)
  --slides-ocr                      Run OCR on extracted slides (requires tesseract). (default: false)
  --no-slides-ocr                   Disable configured slide OCR for this run.
  --slides-dir ‹dir›                Base output dir for slides (default: ./slides). (default: "slides")
  --slides-scene-threshold ‹value›  Scene detection threshold for slide changes (0.1-1.0). (default: "0.3")
  --slides-max ‹count›              Maximum slides to extract (default: 6). (default: "6")
  --slides-min-duration ‹seconds›   Minimum seconds between slides (default: 2). (default: "2")
  --timestamps                      Include timestamps in transcripts when available. (default: false)
  --firecrawl ‹mode›                Firecrawl usage: off, auto (fallback), always (try Firecrawl first). (default: "auto")
  --format ‹format›                 Website/file content format: md|text. For websites: controls the extraction format. For files: controls whether we try to
                                    preprocess to Markdown for model compatibility. (default: text; default in --extract mode for URLs: md)
  --preprocess ‹mode›               Preprocess inputs for model compatibility: off, auto (fallback), always. (choices: "off", "auto", "always", default: "auto")
  --markdown-mode ‹mode›            Markdown conversion: off, auto, llm (force LLM), readability. For websites: converts HTML→Markdown. For YouTube/t
… output truncated …

Assertions:

PASS expect_output: Usage:

How this fits together

The CLI runner converts generated summarize prompts into provider-specific commands and returns the provider response to the CLI and daemon flows. This change affects the agy command’s large-input path while preserving its normal argv path.

flowchart LR
A[Extracted input] --> B[Summarize prompt]
B --> C[agy CLI runner]
C --> D{Fits command limit?}
D -->|Yes| E[Prompt in argv]
D -->|No| F[Private prompt file]
E --> G[agy print mode]
F --> G
G --> H[Summary output]

Decision needed

Question	Recommendation
Should large agy prompts automatically use a file URL instruction as the default, or should summarize retain the current explicit rejection until agy has a supported file-input contract?	Require a supported-version boundary: Document and enforce a verified agy compatibility boundary or fallback so unsupported versions retain the actionable current error.

Why: This is a new default provider capability whose correctness depends on an external CLI’s version-specific prompt interpretation, not solely on local cleanup and argv handling.

Before merge

Resolve merge risk (P1) - Existing users move from a documented actionable large-prompt error to output that depends on agy honoring a file URL instruction; the available real proof covers only agy 1.1.13.
Complete next step (P2) - A maintainer must choose the provider compatibility contract before a repair or merge path can be safely selected.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production versus test delta	production +16 net, tests +123 net, docs 1 line replaced	The narrow runner change is accompanied by focused coverage for offload, permissions, cleanup, and command-limit handling.

Merge-risk options

Maintainer options:

Establish agy compatibility before merge (recommended)
Add a supported-version boundary or fallback proof so installations that cannot consume the file URL keep the current explicit failure.
Accept version-specific provider behavior
Merge with the documented agy 1.1.13 evidence and accept differing behavior on other installed agy versions.

Technical review

Best possible solution:

Define the supported agy file-input compatibility boundary, then either guard/document that boundary with regression proof or retain the existing explicit rejection for unsupported versions.

Do we have a high-confidence way to reproduce the issue?

Yes for the current limitation: current main’s agy runner deterministically rejects prompts over its platform argv threshold, though the PR’s new behavior was live-proven only on agy 1.1.13.

Is this the best way to solve the issue?

Unclear: the temporary-file implementation is narrow and cleanup is covered, but automatic use needs an accepted agy compatibility contract before it replaces the existing explicit error.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against c78ac23b2fc8.

Labels

Label justifications:

P2: This is a bounded provider capability improvement with a compatibility decision but no evidence of an urgent broad outage.
merge-risk: 🚨 compatibility: The PR changes the established large-input failure mode to version-dependent agy file-reference behavior.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body provides after-fix terminal output for a 342 KB input using agy 1.1.13, showing the file-reference path produced a response.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body provides after-fix terminal output for a 342 KB input using agy 1.1.13, showing the file-reference path produced a response.

Evidence

What I checked:

Current-main behavior: Current main intentionally rejects agy prompts above the platform argv limit rather than attempting a file-based input path. (src/llm/cli-runners/plain.ts:84, c78ac23b2fc8)
Proposed implementation: The PR creates a 0600 prompt file, passes a file URL in the print instruction, checks final command size, and removes temporary directories in finally. (src/llm/cli-runners/plain.ts:103, 7babc5447827)
Provider-contract dependency: The new behavior depends on agy treating the PR-generated natural-language file URL instruction as readable content; the supplied proof establishes this for agy 1.1.13 only. (docs/cli.md:178, 7babc5447827)
Real behavior proof: The PR body records a successful 342 KB input run with agy 1.1.13 and observable summary output after the offload path. (7babc5447827)
Area provenance: The current CLI adapter split, including the affected runner surface, dates to Peter Steinberger’s refactor commit. (src/llm/cli-runners/plain.ts:70, a50fb6e89b23)

Likely related people:

steipete: Peter Steinberger introduced the current CLI runner split that owns the agy adapter surface. (role: CLI adapter refactor author; confidence: high; commits: a50fb6e89b23; files: src/llm/cli-runners/plain.ts, src/llm/cli.ts)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

Obtain maintainer confirmation of the supported agy version behavior, or add a compatibility boundary that preserves the current error outside it.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (6 earlier review cycles)

reviewed 2026-08-16T17:53:09.467Z sha f090fa1 :: needs real behavior proof before merge. :: none
reviewed 2026-08-16T18:10:39.479Z sha f090fa1 :: needs maintainer review before merge. :: none
reviewed 2026-08-16T19:38:07.528Z sha f090fa1 :: found issues before merge. :: [P2] Recheck Windows length after offloading the prompt
reviewed 2026-08-16T21:27:52.988Z sha 7babc54 :: needs maintainer review before merge. :: none
reviewed 2026-08-16T21:33:47.956Z sha 7babc54 :: needs maintainer review before merge. :: none
reviewed 2026-08-21T17:02:57.647Z sha 7babc54 :: needs maintainer review before merge. :: none

mvance · 2026-08-16T19:35:28Z

@clawsweeper re-review

clawsweeper · 2026-08-16T19:35:33Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

…nst extraArgs overflow

mvance · 2026-08-16T21:31:45Z

@clawsweeper re-review

clawsweeper · 2026-08-16T21:31:48Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

mvance added 3 commits August 14, 2026 22:40

feat(agy): offload large prompts to temp file for agy CLI

c47d4f6

refactor(agy): include timeout flags in Windows command-length estima…

2e4f7a2

…tion

docs(cli): update agy large prompt documentation for temp file offloa…

f090fa1

…ding

fix(agy): recheck final command length across platforms to guard agai…

7babc54

…nst extraArgs overflow

Navigation Menu

feat(agy): offload large prompts to temp file for agy CLI - #389

feat(agy): offload large prompts to temp file for agy CLI#389
mvance wants to merge 4 commits into
steipete:mainfrom
mvance:feat/agy-large-prompt-tempfile

mvance commented Aug 16, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Aug 16, 2026

Uh oh!

clawsweeper Bot commented Aug 16, 2026 •

edited

Loading

Security

Review metrics

Merge-risk options

Technical review

Labels

Evidence

Rank-up moves

Rating scale

Workflow

History

Uh oh!

mvance commented Aug 16, 2026

Uh oh!

clawsweeper Bot commented Aug 16, 2026 •

edited

Loading

Uh oh!

mvance commented Aug 16, 2026

Uh oh!

clawsweeper Bot commented Aug 16, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

mvance commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rationale

Proposed Solution

Live Behavior Proof (Real Execution)

Environment & Input

Terminal Output

Tests & Quality Gate

Uh oh!

clawsweeper Bot commented Aug 16, 2026

Uh oh!

clawsweeper Bot commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ClawSweeper review

What this changes

Merge readiness

Review scores

Verification

Live Verification

How this fits together

Decision needed

Before merge

Security

Review metrics

Merge-risk options

Technical review

Labels

Evidence

Rank-up moves

Rating scale

Workflow

History

Uh oh!

mvance commented Aug 16, 2026

Uh oh!

clawsweeper Bot commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mvance commented Aug 16, 2026

Uh oh!

clawsweeper Bot commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mvance commented Aug 16, 2026 •

edited

Loading

clawsweeper Bot commented Aug 16, 2026 •

edited

Loading

clawsweeper Bot commented Aug 16, 2026 •

edited

Loading

clawsweeper Bot commented Aug 16, 2026 •

edited

Loading