[spec] get-actor-version: fix the omitted-file hint and the hidden-URL Git refusal

[jirispilka]

Problem

Two user-facing text defects in get-actor-version (#1450, on master since 0c1c93e, shipped in 0.17.2). Both came in with commits pushed after the two approvals (41285bc, 1b372e9) and were found by calling the tool over mcpc against the live API on 2026-10-01, build of head 0a183a5 with --tools=source,actors. Outputs are verbatim.

1. The oversize-file hint tells the agent to do what it just did, and for a binary file it points at a dead end.

mcpc --json @p1450 tools-call get-actor-version '{"actor":"jiri.spilka/apify-mcp-server","paths":["package-lock.json"]}'
→ isError=false, contents=[], omittedPaths=["package-lock.json"]
→ "Read version 0.1 of jiri.spilka/apify-mcp-server. Left out over the 256 KiB limit: package-lock.json;
   ask for a file alone, or for part of it with startLine and lineCount."

The file (488,496 B) was already asked for alone. A binary file gets the same hint, and following it fails:

mcpc --json @p1450 tools-call get-actor-version '{"actor":"jiri.spilka/python-start-starlette","paths":["temp_file.zip"]}'
→ "Left out over the 256 KiB limit: temp_file.zip; ask for a file alone, or for part of it with startLine and lineCount."

mcpc --json @p1450 tools-call get-actor-version '{"actor":"jiri.spilka/python-start-starlette","paths":["temp_file.zip"],"startLine":1,"lineCount":10}'
→ isError=true: "temp_file.zip is returned as base64, and startLine and lineCount work only on text files."

A binary file whose base64 exceeds 256 KiB (about 192 KiB raw) cannot be read by any call, and neither the hint nor the tool description says so. Hint: src/tools/source/get_actor_version.ts:289; base64 refusal: line 164.

2. A Git-sourced version whose repository URL the API hides is refused with "use the repository", naming none.

mcpc --json @p1450 tools-call get-actor-version '{"actor":"apify/instagram-scraper","versionNumber":"0.0"}'
→ "Version 0.0 of apify/instagram-scraper has its files in the Git repository, not stored on Apify,
   so this tool cannot work on them; use the repository."

For an own Actor the URL is present (jiri.spilka/weather-mcp-server 0.1 names https://github.com/apify/mcp-servers#main:weather-mcp-server). The API omits gitRepoUrl for Actors the caller cannot modify. Line 148 already handles that for SOURCE_FILES ("the API hides it from accounts that cannot modify the Actor"); the Git branch at lines 123-124 does not.

How these got through. The PR was tested end to end with mcpc by a reviewer, but on commit 20b4796, before the two commits that changed this text. Re-running the two changed cases over mcpc after those commits (one oversize file alone, one Git version of an Actor you don't own) shows both defects in two calls. Post-approval commits that change tool text should get an mcpc pass before merge, and the #1452 evals, when they exist, should include an oversize text file and an oversize binary file so the dead end shows up as a failed task.

Proposed solution

Both in src/tools/source/get_actor_version.ts:

1. Build the omitted-file hint from the request. One path requested: drop "ask for a file alone". Any omitted file is base64: say binary files over 256 KiB cannot be returned by this tool, instead of suggesting startLine/lineCount. State the limit in the tool description (lines 231-234) so the agent knows before calling.
2. When gitRepoUrl is absent, reuse the line 148 wording: the API hides the repository from accounts that cannot modify the Actor; ask the owner.

Tests: no "alone" hint for a single requested path; binary message for a base64 omitted file; hidden-URL message for a Git version without gitRepoUrl.

Plan

• Hint, description and Git-refusal text, with the three tests above, one PR.

Related, not in scope: MQ37's #1450 review note that files lists every file even when paths are given is a design choice to settle before #1453 pins the shape. The versionNumber: 0.0 → "0" coercion (reproduced live on the same build) is the shared ajv coerceTypes behaviour and belongs in its own issue.