[khushalsonawat]

Stacked on #245 (TH-8951), which is stacked on #225 (TH-8804) and #224 (TH-8806). The base is feat/TH-8951-read-without-build, so the diff shows only TH-8950. It retargets down the stack as those merge.

Summary

The platform's Agents tab needs a list of the agents in a repo before anything is built, so a person can pick one to create. This PR adds --find-agents to the authoring command. It reads the repo at one commit (or an upload) without installing or running anything, and writes /work/reading/agents.json in the shape AgentScanSerializer reads, plus cost.json. It uses #245's shared reading helper. Exit 0 means a file was written (found, none or error); 1 and 78 mean failure.json.

• The walk (scan_walk.py) reads each file once, the repo's own code before test and example folders, and finds candidates: framework builds, langgraph.json graphs, agent.py, provider clients. It joins files into agents by their imports, so a side-folder script or a weaker file never swallows a stronger one. An agent's folder counts only agents of its own project.
• The framework word (scan_folders.py) is TH-8805's answer for each agent's folder, with a build's limits. It runs in one child process that the scan's clock can stop.
• The model step (scan_ai.py) is the only paid part ($0.31–0.50 measured). It runs when the walk found no agent, found agents only in test or example folders, or found only a weak sign (a bare client or chat model) beside TypeScript or JavaScript, which the walk can't read; and only with 360 s left on the clock and the walk not stopped. Its read/glob/grep tools stay inside the source. Only the paths it names are kept, once checked, and nothing it writes reaches the file. If it fails, the walk's rows are still written with truncated: true; only a scan with no rows writes scan_model_error.
• Faults: a fault in one file leaves that file unread; any other fault in the kit ends as scan_crashed (retryable). Faults that are still absorbed log their trace through the reading helper's secret mask.
• The file (scan_document.py): names, evidence sentences and paths are built to fit the serializer's rules. The file is checked against a copy of them (fixture pinned to e07d56fcd), and at most 50 agents are kept.

Settings:

• ALK_SCAN_MAX_SECONDS: the clock, 1,200 s;
• ALK_SCAN_AI_MAX_SECONDS: the model step's limit, 600 s;
• the hard stop: the clock + 600 s.

The sandbox needs 4,096 MB, 2 CPU and a lifetime of at least 2,400 s.

Why one PR: find, none and error is one agreed contract with the platform, and TH-8824 needs both halves. The walk alone would answer none for a TypeScript-only repo. The model tools' {a,b} and **/ glob support came from a measured failure on vercel/ai-chatbot (false "No file matches"), not from the spec.

Ticket: TH-8950.

Known limits

• The step that joins files into agents gets the walk's deadline plus 120 s; past it the scan ends as scan_timed_out with no rows, even if the walk had found some.
• The walk reads at most 40,000 source files and 256 MiB; past that it stops with scan_limit_reached, or truncated if it found agents. What it holds grows with the names each file imports (about 33 KB a file at 200 imported names, a 1,389 MB peak at 40,000 such files), so the cap keeps that inside the 4,096 MB sandbox. A budget on the names held, instead of a file count, is a follow-up.
• An agent whose path breaks the platform's path rule is left out with truncated: true, or gets error agent_path_unsupported when nothing else is found. Next.js route folders such as app/(chat)/ hit this; listing them needs the rule to allow ( and ).
• The framework word is one per folder, so a folder holding several frameworks reads as unknown.
• A Python repo that also holds a TypeScript agent lists only the Python one when the walk finds a strong candidate.
• Two agents in one folder are both listed at low confidence; a build can't tell them apart.
• Measured on a laptop, not on the sandbox:
  • agent-learning-kit: 8 s, 769 MB, 21 rows, $0;
  • future-agi monorepo: 13 s, 637 MB, 11 rows, $0;
  • vercel/ai-chatbot with the model step: 14 s, 534 MB, $0.31.
• Not reviewed yet:
  • the last review round's fixes, and the fixes for this PR's first review;
  • the handling of model-named paths that break the path rule;
  • glob {a,b} and **/ matching in the model's tools.
• Pre-existing: authoring_entrypoint.py imports sys and shutil twice (ruff F811), already on the base.

Changes since the 10 Nov approval (4eb45c60)

• 45eb82ba: the cost-note catch logs its trace (your P3).
• 884043ca: one unreadable file no longer stops an AI row's description; detect_framework gains raise_faults (off for builds) so the scan sees a fault in the framework check and marks the row unfinished; a tool fault keeps its cause.
• 6aeb4665: settings templates are read with the repo's own code; one trace per unforeseen reader fault; ALK_SCAN_AI_MAX_SECONDS read when the model step is asked; tests isolated from the environment. It also raised the file cap to 200,000, which the next round found unsafe for memory.
• 81d16b54: a file over 1 MiB marks an AI row short instead of being skipped silently.
• b46311ad: the file cap is 40,000 (from 20,000 at your review), sized by memory; the partial-row sentence says files couldn't be read.
• b8970348: the step after the walk (joining files into agents) checks the walk's deadline plus 120 s and ends as a clock stop, so a huge import graph ends in scan_timed_out instead of the hard stop (your P2); the two-pass test pins the template order (your P3).
• 4dcea5c3: merge of feat(harness): read an agent without building it #245 at edb69263 (no change to this PR's own diff).
• af8e86e5: the join counts candidate pairs and, past 5,000,000 (about 90 MB), ends with the walk's limit result (your P3 follow-up).

Verification

• uv run ruff check on the changed files: clean apart from the pre-existing F811 above
• Focused pytest targets, one file at a time, on Python 3.12.14 and 3.12.3:
  • tests/harness/test_scan_walk.py: 92 passed
  • tests/harness/test_scan_folders.py: 7 passed
  • tests/harness/test_scan_document.py: 17 passed
  • tests/harness/test_scan_ai.py: 59 passed
  • tests/harness/test_agent_scan.py: 63 passed
  • tests/harness/test_authoring_entrypoint_find_agents.py: 5 passed
  • neighbours, on feat(harness): read an agent without building it #245 at ee163b0: test_reading_entry.py 61, test_agent_reading.py 88, test_framework_detection.py 251 passed (framework_detection._Work takes an optional limit, so the walk reuses it; detect_framework takes raise_faults, off for builds, so the scan sees a fault in the check)
• Full uv run pytest -q: not run
• TypeScript build/test: not touched
• agent-learn release-proof: not touched

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's internal command, no user docs
• New release claim has executable gate coverage: no release claim
• No hosted-service dependency was added to release-gated examples
• Security-sensitive output is redacted or justified: evidence is fixed sentences only, settings are names only, and secret-like files are hidden from the model's tools

[cdileep23]

Please check the comments.

[cdileep23]

Please check the comments.

[cdileep23]

Please check the comments.

[khushalsonawat]

Since your approval at 4eb45c6 there are five commits, listed in the body under "Changes since the 10 Nov approval". The two that change behaviour beyond your comments: detect_framework gains raise_faults (off for builds), and the walk's file cap is 40,000, sized by memory. Could you take another look?

[cdileep23]

Please check the comments.