fix: search-actors says results ended on a mid-list empty page #1593

Problem

The Store search API applies offset/limit before it filters some results out. Pages come back short, or empty, while more results follow. Since #1568, search-actors reports an empty page with an offset as No Actors past offset N…. That claims the results have ended, so an agent stops paging even though later offsets still return Actors.

Reproduce (production)

mcpc connect "https://mcp.apify.com/?tools=search-actors" @repro
# limit 10 returns 9 Actors, not 10
mcpc @repro tools-call search-actors keywords:='"czech real estate"' limit:=10
# page with limit 1: offset 8 is empty, offset 9 is not
for o in 7 8 9; do mcpc --json @repro tools-call search-actors keywords:='"czech real estate"' limit:=1 offset:=$o | jq -c '[.structuredContent.actors[].fullName]'; done

Observed with limit:=1, offsets 0–9:

On staging, keywords:'""' limit:=1 is empty at offsets 1–3 and returns an Actor at offset 4.

Affected

• search-actors paging with small limit values.
• From 0.18.3 the empty page states that the results have ended. In 0.18.2 it only shows the generic no-results guidance.

Implementation handoff (2026-10-15)

Scope

• Prefer the minimal wording fix: No Actors returned at offset N for the search query "...". This describes the page without claiming that later pages are empty.
• The current shared search helper returns only items, discarding pagination metadata. Do not expand its return type solely to obtain total. Only claim the end if reliable metadata already proves it.
• Keep the offset-zero guidance distinct from an empty page at a later offset. Do not add a retry command, another API call, or a new pagination algorithm.
• Update the helper docstring that assumes a nonzero empty page lies past the last result.

Regression coverage

• Write and run a failing regression test first for an empty page at a nonzero offset that must not claim the end. Cover the shared helper and both default and widget responses, including default structured instructions. Preserve the widget output schema.
• Keep deterministic tests mocked. The live Store examples above are observations, not stable fixtures.
• Probe the listed linkedin jobs offset 4 and czech real estate offsets 8 and 9 through mcpc, in default and Apps modes. If those pages have changed, report that and inspect a bounded nearby range; do not change the test to depend on today's live contents.

Verification and delivery

• Follow the current root and child AGENTS.md / CLAUDE.md, CONTRIBUTING.md and TOOL_GUIDELINES.md. Keep one concern per PR; no cleanup or refactoring.
• New bug fixes need a failing regression test before implementation. Retain the existing test-first evidence when continuing an existing fix.
• Before pushing, run pnpm run type-check, pnpm run lint, pnpm run test:unit, pnpm run format and pnpm run check:agents. Review the formatted diff. Do not run integration tests.
• Build before mcpc. Start the local HTTP server with PORT=3001 pnpm start (use an isolated port if another session owns 3001). Probe this exact selection, substituting only the local origin:

http://localhost:3001/?tools=search-actors,search-actors-widget,fetch-actor-details,fetch-actor-details-widget,search-apify-docs,fetch-apify-docs,get-actor-run,get-actor-run-list,get-actor-run-log,abort-actor-run,get-dataset,get-dataset-items,get-dataset-schema,get-dataset-list,get-key-value-store,get-key-value-store-keys,get-key-value-store-record,get-key-value-store-list,apify/rag-web-browser,apify/website-content-crawler,apify/screenshot-url,apify/web-fetch,report-problem&client=claude

• Authenticate with the existing APIFY_TOKEN without displaying it. Add &ui=true for Apps mode. Expect the 21-tool default surface and 23-tool Apps surface; compare actual served names, including normalized Actor tool names. Keep telemetry enabled when verifying that the explicitly selected report-problem tool is served.
• Use mcpc for the protocol probes and the Apify CLI for ground-truth IDs. Do not print credentials, proxy passwords or signing secrets. Do not submit a problem report or start paid runs just to verify wording.
• Use Conventional Commit titles and disclose AI use. Follow the PR template and leave the human-written notes section for the author. Keep PR descriptions neutral, with observed evidence and any remaining checks.
• A local result is not a production result. Hosted availability requires a public package release, the internal dependency bump and deployment; record those as separate follow-up work.