[khushalsonawat]

Stacked on #225 (TH-8804), which is stacked on #224 (TH-8806). This PR's base is feat/TH-8804-source-subfolder, so its diff shows only TH-8951. It retargets down the stack as those merge.

Summary

The platform's Agents tab creates an agent and its first version from a repo before any environment is built, and it needs the agent's description to show. This PR adds a --read-agent-only mode to the hosted authoring command. It runs only the agent reading a build already does, leaves the result in --output (/work/reading/ on the hosted route), and stops. Nothing is built, and there is no new callback.

A run leaves:

• contract.json: the raw reading;
• agent.json: the agent document;
• cost.json: the build's spend keys plus complete, whenever the reading reaches its work. A run refused before that leaves none, and none means nothing was spent. The refusals are: a bad job, a job check that crashes, a provider-defined agent, a wrong source kind, a non-empty output folder, or a failed first cost write;
• failure.json: on failure only, in the HarnessFailure shape.

Exit 0 means read, 78 not retryable, 1 retryable. When failure.json is present, its retryable decides.

Ticket: TH-8951.

How it works

• reading_entry.py, a helper shared with TH-8950's --find-agents (contract reading-entry v0.17). It handles:
  • the job check;
  • masking secrets files;
  • a soft limit of 1,800 s (ALK_READING_MAX_DURATION_SECONDS) and a hard timer 300 s after it;
  • a cost.json that starts complete: false and is rewritten after each turn.
• agent_reading.py and reading_result.py, the reading. It opens its stage exactly as cli._understand does, through one shared helper (understand.reading_settings): 70 or 140 turns, thinking on, and the setup-contract gate for generic jobs. It uses the same model and gate as a build. Browser agents are refused by TH-8806's rule (agent_type_unsupported, 78).
• Cost.
  • Claude reports running totals within one session, so each turn records only its difference from the last.
  • complete is false after the soft limit, after a stalled stream, after any unpriced turn, and after any status-less provider error, because a cut request may still be billed.
• Turn limits are final and never retried. A turn limit is an max_turns or error_max_turns outcome, or ADK's whole "Max number of llm calls limit of n exceeded" message. If the last turn hit the limit, that wins over an earlier status-less failure.
• What is retried: status-less failures, 408, 409, 429 and 5xx. Other 4xx responses and a forbidden billed model are not.
• A contract the gate saved is kept through a later fault or a timeout, so the platform doesn't pay for the reading twice.

Release notes

• The sandbox needs at least 2,400 s, which is unchanged. Start-up must fit in 240 s. The hard limit is now 2,100 s (soft 1,800 s + 300 s), so the sandbox must outlast start-up + 2,100 s + 60 s. The margin grew from 180 s on 10 Nov, so a saved reading's document always has room after the longest stop.
• A status-less error that ends with a saved contract now gives exit 0 with complete: false. The platform charges total_usd either way and keeps the flag.

Known limits

• A reading that reaches the provider and then dies before its first request reports "the model provider failed" rather than "crashed". The exit is the same; only the code differs. Telling them apart needs a change in Stage or a backend.
• A connect_only job with an http or auto connector is refused, though the build loads no provider definition for it. The refusal fails closed, with a clear 78 before any spend.
• When a turn limit on the last turn is followed by an exception, the reading ends as a turn limit, not as a crash. No test covers that order.
• A browser agent in a large repo is read in full before the refusal, because TH-8806's check runs at save time. On browser-use that cost $6.06 and took 7.7 minutes.

Verification

• tests/harness/test_reading_entry.py: 61 passed. tests/harness/test_agent_reading.py: 105 passed. tests/harness/test_scenario_source_provision_agent.py: 24 passed (at d1f968cc). Run on a locked venv (claude-agent-sdk 0.2.156, google-adk 2.7.1, Python 3.12.14), each whole file in one process. Both are added to sdk-smoke.yml.
• 61 planted bugs from the plan, plus each review's and each fixer's revert checks: all caught except two plants with no site in the code.
• Real run on Claude Sonnet, through a local gateway under a Gemini-named alias, priced at that alias's rate:

Agent	Time	Cost	Result
Small chat agent (LangChain), after Dileep's review	80 s	$0.87	exit 0, chat, complete: true
Small chat agent (LangChain), before it	113 s	$1.11	exit 0, chat, complete: true
Chat agent in a subfolder (Next.js)	102 s	$1.00	exit 0, chat, folder recorded
browser-use	459 s	$6.06	exit 78, agent_type_unsupported
Small agent, gateway stopped	358 s	$0.00	exit 1, retryable model error
Small agent, 40 s soft limit	42 s	$0.60	exit 78, agent_reading_timed_out, complete: false

The interrupted Claude turn reported its cost. The gateway keeps no request log, so cost.json wasn't checked against the gateway's own meter. Gemini wasn't run against a real model; it's covered by tests that drive the real ADK runner with an in-memory model.

• Dileep's review (16 comments) was fixed in 159c5807 and bd198d59. One cold review round cleared those two commits, with no High. Its findings went in afterwards as ee163b04, unreviewed: tests that pin the timeout and crash paths, a backstop exit after the work returns, and tighter masking of the logs. Each of those fixes has a test that fails without it. Comment 5 became TH-9057.

• Three cold reviews of the change (Lane N). The third cleared with no High. The fixes after it are unreviewed:

  • the turn-limit rule's count signal removed and the message matched whole;
  • the last-turn precedence;
  • three new tests;
  • three test fakes corrected.

• Dileep's second review (7 comments) was fixed in 4617eecf, ef177b36 and 49c1f4c6. Two review rounds ran.

• Dileep's third review (5 P3s, with his approval) was fixed in d1f968cc, with no review round.

  • The last round's fixes went in afterwards, unreviewed, each with a test that fails without it:
    • the 300 s margin;
    • the interrupt as its own task;
    • a URL the parser refuses is now redacted whole;
    • the contract is read once.
  • feat(harness): build an agent from a repo's subfolder #225 at 76fcb60d was merged in. The browser test now expects feat(harness): refuse browser, computer-use and crawler agents #224's one second look before the refusal (edb69263).

Checklist

• Public API names stay under agent_learning.*, agent-learn, or @future-agi/agent-learning-kit
• New user-facing workflow has docs or an example: the platform route isn't built yet (TH-8824)
• New release claim has executable gate coverage
• No hosted-service dependency was added to release-gated examples
• Security-sensitive output is redacted or justified

Closes TH-8951

🤖 Generated with Claude Code

[cdileep23]

Please check the comments.

[cdileep23]

Please check the comments.

[cdileep23]

Please check the comments.