feat: Add get-actor-build tool

[DaveHanns]

What

Adds get-actor-build, a read-only tool in a new opt-in deploy category. It returns an Actor build's status and the last N lines of its build log, plus a one-line summary and next step.

Why

An agent developing an Actor over MCP can start a build (call-actor already accepts callOptions.build) but has no way to see whether the build finished or why it failed; today it has to shell out to apify-cli or call the REST API directly. This tool closes that gap in the build and debug part of the loop.

Relates to #1217 (Deploy Actor source code using MCP). The deploy contract itself stays blocked on apify-core#29044; build inspection does not depend on it.

How

• apify-client calls: client.build(buildId).get() for the build document and client.build(buildId).log().get() for the log, sliced to the trailing lines with the same tail logic as get-actor-log.
• Registration: HELPER_TOOLS.ACTOR_BUILD_GET, src/tools/deploy/get_actor_build.ts, new deploy category in src/tools/registry.ts (not enabled by default, not auto-injected, mode-agnostic).
• Input: buildId (string, required) and lines (integer 0..50, default 20; 0 returns the entire log). Zod schema, fixZodSchemaRequired for the default.
• Output: structuredContent = { build: { id, actorId, buildNumber, status, startedAt, finishedAt, apifyConsoleUrl? }, logTail: string[] } (allowlisted via toBuildResult, internal fields such as userId, meta, options, inspectorId do not leak). content[0] mirrors it as JSON, content[1] is summary plus next step. A SUCCEEDED build suggests call-actor with callOptions.build only when that tool is loaded (loadedToolNames), otherwise "The build is ready to run."; a failed build points at the log tail; a non-terminal build asks to call again in about 10 seconds.
• Not found: respondUserError("Build with ID '<id>' not found."), the same shape as get-actor-log (fix: Return not-found error from get-actor-log for missing runs #1234).
• Console link: new buildConsoleBuildUrl in src/utils/console_link.ts; apifyConsoleUrl and the verbatim-links nudge appear only for Console UI token sessions, following the apify-core#27286 policy the run and storage tools use.
• Docs: README category bullet and tool-table row, src/tools/AGENTS.md file list.

Testing

• pnpm run type-check, lint, format, test:unit, check:agents pass locally (99 files, 1571 unit tests, 1 pre-existing skip).
• New tests/unit/tools.get_actor_build.test.ts (14 tests): allowlisted fields, log tail slicing and the default of 20 lines, lines: 0 returns the entire log, missing log yields [], output-schema conformance, not-found soft fail with the exact message, ajv rejection of lines: 51 and an empty buildId, Console link for UI token sessions, and every nextStep branch with and without call-actor loaded. console_link.test.ts covers buildConsoleBuildUrl for personal, org and non-Console contexts; tools.mode_contract.test.ts pins the deploy category in both modes.
• Not run: integration tests and mcpc probing (need APIFY_TOKEN).

Notes for reviewers

• Adds a new structuredContent shape consumed by the hosted server (apify-mcp-server-internal may need a contract test).
• paymentRequired: true mirrors get-actor-run and get-actor-log. Confirm this is intended for build inspection.
• lines: 51 is rejected by the AJV input validation in tool_call_engine before call runs, so the test checks ajvValidate rather than a soft-fail result; re-validating inside the tool body is against the repo rules.
• An existing build with an empty log yields logTail: [], the same as a missing log.
• build_helpers.ts reuses toIsoString from actors/actor_run_response.ts and the tool reuses apifyConsoleLinkText from storage/storage_helpers.ts rather than duplicating them; say if you prefer those moved to a shared utils module.

AI disclosure: implemented with Claude Code; awaiting human review.

🤖 Generated with Claude Code